1 #ifndef LIBQMSK_SSL_H

     2 #define LIBQMSK_SSL_H

     3 

     4 /**

     5  * @file

     6  *

     7  * SSL transport implementation.

     8  */

     9 #include "transport.h"

    10 #include <stdbool.h>

    11 

    12 /**

    13  * SSL client credentials for use with ssl_client_credentials/sock_ssl_connect

    14  */

    15 struct ssl_client_cred;

    16 

    17 /**

    18  * Set up SSL client credentials for use with sock_ssl_connect. This includes information both required to identify

    19  * ourselves to the server, as well as to verify the server.

    20  *

    21  * To verify the server's certificate, pass in a path to a file containing the CA certificate(s) that should be used to

    22  * verify the server's certificate, and then either give `verify` as true to force verification, or false to simply

    23  * warn. XXX: not entirely true

    24  *

    25  * To supply a client certificate to the server, pass in the paths to the cert/pkey files. If given as NULL, an

    26  * anonymous client certificate will be used. Both must be supplied if given.

    27  *

    28  * The newly created SSL client credential will initially have a refcount of one, and can then be used with sock_ssl_connect.

    29  *

    30  * @param ctx_cred the newly created client credentials are returned via this

    31  * @param cafile_path given as non-NULL to load trusted certs for verification from the given path

    32  * @param verify force verification of the peer cert

    33  * @param cert_path path to the client certificate file, or NULL

    34  * @param pkey_path path to the client private key, or NULL

    35  * @param err returned error info

    36  */

    37 err_t ssl_client_cred_create (struct ssl_client_cred **ctx_cred,

    38         const char *cafile_path, bool verify,

    39         const char *cert_path, const char *pkey_path,

    40         error_t *err

    41 );

    42 

    43 /**

    44  * Aquire a referenec for the given cred.

    45  */

    46 void ssl_client_cred_get (struct ssl_client_cred *cred);

    47 

    48 /**

    49  * Release a reference allocated for the given cred.

    50  */

    51 void ssl_client_cred_put (struct ssl_client_cred *cred);

    52 

    53 /**

    54  * Start a non-blocking SSL connect/handshake to the given host/service. The socket will not yet be connected when the

    55  * function returns, but rather, the eventual redyness/failure of the connect/handshake will be indicated later using

    56  * the given \a cb_func.

    57  *

    58  * The given ssl_client_cred should either be NULL to use an anonymous client cert and not verify the server cert,

    59  * or a ssl_client_cred allocated using ssl_client_cred_create(). The contexts are reference-counted, so once

    60  * a cred context has been released, it will be destroyed once the last connection using it is destroyed.

    61  * 

    62  * @param info the transport setup info

    63  * @param transport_ptr returned transport

    64  * @param hostname the hostname to connect to

    65  * @param service the TCP service name (i.e. port) to connect to

    66  * @param cred the SSL client credentials to use, if not NULL

    67  * @param err returned error info

    68  */

    69 err_t ssl_connect (const struct transport_info *info, transport_t **transport_ptr, 

    70         const char *hostname, const char *service,

    71         struct ssl_client_cred *cred,

    72         error_t *err

    73     );

    74 

    75 #endif