1 #ifndef SSL_H |
|
2 #define 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 |
|
76 |
|
77 #endif /* SSL_H */ |
|