1

#ifndef SOCK_SSL_H

     2

#define SOCK_SSL_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * SSL-specific functionality as related to sock.h

     8

 */

     9

#include "sock.h"

    10

    11

/**

    12

 * SSL client credentials for use with sock_ssl_client_credentials/sock_ssl_connect

    13

 */

    14

struct sock_ssl_client_cred;

    15

    16

/**

    17

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

    18

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

    19

 *

    20

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

    21

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

    22

 * warn. XXX: not entirely true

    23

 *

    24

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

    25

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

    26

 *

    27

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

    28

 *

    29

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

    30

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

    31

 * @param verify force verification of the peer cert

    32

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

    33

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

    34

 * @param err returned error info

    35

 */

    36

err_t sock_ssl_client_cred_create (struct sock_ssl_client_cred **ctx_cred,

    37

        const char *cafile_path, bool verify,

    38

        const char *cert_path, const char *pkey_path,

    39

        struct error_info *err

    40

);

    41

    42

/**

    43

 * Aquire a referenec for the given cred.

    44

 */

    45

void sock_ssl_client_cred_get (struct sock_ssl_client_cred *cred);

    46

    47

/**

    48

 * Release a reference allocated for the given cred.

    49

 */

    50

void sock_ssl_client_cred_put (struct sock_ssl_client_cred *cred);

    51

    52

/**

    53

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

    54

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

    55

 * the given \a cb_func.

    56

 *

    57

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

    58

 * or a sock_ssl_client_cred allocated using sock_ssl_client_cred_create(). The contexts are reference-counted, so once

    59

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

    60

 * 

    61

 * @param sock_ptr the new sock_stream

    62

 * @param hostname the hostname to connect to

    63

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

    64

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

    65

 * @param cb_func the callback for connection/handshake completion

    66

 * @param cb_arg the callback context argument

    67

 * @param err returned error info

    68

 */

    69

err_t sock_ssl_connect_async (struct sock_stream **sock_ptr, 

    70

        const char *hostname, const char *service,

    71

        struct sock_ssl_client_cred *cred,

    72

        sock_stream_connect_cb cb_func, void *cb_arg, 

    73

        struct error_info *err

    74

    );

    75

    76

    77

    78

#endif /* SOCK_SSL_H */