proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
ssl.h
Go to the documentation of this file.
1 #ifndef PROTON_SSL_H
2 #define PROTON_SSL_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <sys/types.h>
26 #include <stdbool.h>
27 #include <proton/engine.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /** @file
34  * API for using SSL with the Transport Layer.
35  *
36  * A Transport may be configured to use SSL for encryption and/or authentication. A
37  * Transport can be configured as either an "SSL client" or an "SSL server". An SSL
38  * client is the party that proactively establishes a connection to an SSL server. An SSL
39  * server is the party that accepts a connection request from a remote SSL client.
40  *
41  * This SSL implementation defines the following objects:
42 
43  * @li A top-level object that stores the configuration used by one or more SSL
44  * sessions (pn_ssl_domain_t).
45  * @li A per-connection SSL session object that performs the encryption/authentication
46  * associated with the transport (pn_ssl_t).
47  * @li The encryption parameters negotiated for the SSL session (pn_ssl_state_t).
48  *
49  * A pn_ssl_domain_t object must be created and configured before an SSL session can be
50  * established. The pn_ssl_domain_t is used to construct an SSL session (pn_ssl_t). The
51  * session "adopts" its configuration from the pn_ssl_domain_t that was used to create it.
52  * For example, pn_ssl_domain_t can be configured as either a "client" or a "server". SSL
53  * sessions constructed from this domain will perform the corresponding role (either
54  * client or server).
55  *
56  * Some per-session attributes - such as peer verification mode - may be overridden on a
57  * per-session basis from the default provided by the parent pn_ssl_domain_t.
58  *
59  * If either an SSL server or client needs to identify itself with the remote node, it
60  * must have its SSL certificate configured (see ::pn_ssl_domain_set_credentials()).
61  *
62  * If either an SSL server or client needs to verify the identity of the remote node, it
63  * must have its database of trusted CAs configured (see ::pn_ssl_domain_set_trusted_ca_db()).
64  *
65  * An SSL server connection may allow the remote client to connect without SSL (eg. "in
66  * the clear"), see ::pn_ssl_allow_unsecured_client().
67  *
68  * The level of verification required of the remote may be configured (see
69  * ::pn_ssl_domain_set_default_peer_authentication ::pn_ssl_set_peer_authentication,
70  * ::pn_ssl_get_peer_authentication).
71  *
72  * Support for SSL Client Session resume is provided (see ::pn_ssl_get_state,
73  * ::pn_ssl_resume_state).
74  */
75 
77 typedef struct pn_ssl_t pn_ssl_t;
78 
79 /** Determines the type of SSL endpoint. */
80 typedef enum {
81  PN_SSL_MODE_CLIENT=1, /**< Local connection endpoint is an SSL client */
82  PN_SSL_MODE_SERVER /**< Local connection endpoint is an SSL server */
84 
85 /** Indicates whether an SSL session has been resumed. */
86 typedef enum {
87  PN_SSL_RESUME_UNKNOWN, /**< Session resume state unknown/not supported */
88  PN_SSL_RESUME_NEW, /**< Session renegotiated - not resumed */
89  PN_SSL_RESUME_REUSED /**< Session resumed from previous session. */
91 
92 /** Create an SSL configuration domain
93  *
94  * This method allocates an SSL domain object. This object is used to hold the SSL
95  * configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is
96  * allocated from this object.
97  *
98  * @param[in] mode the role, client or server, assumed by all SSL sessions created
99  * with this domain.
100  * @return a pointer to the SSL domain, if SSL support is present.
101  */
103 
104 /** Release an SSL configuration domain
105  *
106  * This method frees an SSL domain object allocated by ::pn_ssl_domain.
107  * @param[in] domain the domain to destroy.
108  */
109 void pn_ssl_domain_free( pn_ssl_domain_t *domain );
110 
111 /** Set the certificate that identifies the local node to the remote.
112  *
113  * This certificate establishes the identity for the local node for all SSL sessions
114  * created from this domain. It will be sent to the remote if the remote needs to verify
115  * the identity of this node. This may be used for both SSL servers and SSL clients (if
116  * client authentication is required by the server).
117  *
118  * @note This setting effects only those pn_ssl_t objects created after this call
119  * returns. pn_ssl_t objects created before invoking this method will use the domain's
120  * previous setting.
121  *
122  * @param[in] domain the ssl domain that will use this certificate.
123  * @param[in] certificate_file path to file/database containing the identifying
124  * certificate.
125  * @param[in] private_key_file path to file/database containing the private key used to
126  * sign the certificate
127  * @param[in] password the password used to sign the key, else NULL if key is not
128  * protected.
129  * @return 0 on success
130  */
132  const char *certificate_file,
133  const char *private_key_file,
134  const char *password);
135 
136 /** Configure the set of trusted CA certificates used by this domain to verify peers.
137  *
138  * If the local SSL client/server needs to verify the identity of the remote, it must
139  * validate the signature of the remote's certificate. This function sets the database of
140  * trusted CAs that will be used to verify the signature of the remote's certificate.
141  *
142  * @note This setting effects only those pn_ssl_t objects created after this call
143  * returns. pn_ssl_t objects created before invoking this method will use the domain's
144  * previous setting.
145  *
146  * @param[in] domain the ssl domain that will use the database.
147  * @param[in] certificate_db database of trusted CAs, used to authenticate the peer.
148  * @return 0 on success
149  */
151  const char *certificate_db);
152 
153 /** Determines the level of peer validation.
154  *
155  * ANONYMOUS_PEER does not require a valid certificate, and permits use of ciphers that
156  * do not provide authentication.
157  *
158  * VERIFY_PEER will only connect to those peers that provide a valid identifying
159  * certificate signed by a trusted CA and are using an authenticated cipher.
160  *
161  * VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's identity as
162  * contained in the certificate to be valid (see ::pn_ssl_set_peer_hostname).
163  *
164  * ANONYMOUS_PEER is configured by default.
165  */
166 typedef enum {
167  PN_SSL_VERIFY_NULL=0, /**< internal use only */
168  PN_SSL_VERIFY_PEER, /**< require peer to provide a valid identifying certificate */
169  PN_SSL_ANONYMOUS_PEER, /**< do not require a certificate nor cipher authorization */
170  PN_SSL_VERIFY_PEER_NAME,/**< require valid certificate and matching name */
172 
173 /** Configure the level of verification used on the peer certificate.
174  *
175  * This method controls how the peer's certificate is validated, if at all. By default,
176  * neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER).
177  * Once certificates and trusted CAs are configured, peer verification can be enabled.
178  *
179  * @note In order to verify a peer, a trusted CA must be configured. See
180  * ::pn_ssl_set_trusted_ca_db().
181  *
182  * @note Servers must provide their own certificate when verifying a peer. See
183  * ::pn_ssl_set_credentials().
184  *
185  * @note This setting effects only those pn_ssl_t objects created after this call
186  * returns. pn_ssl_t objects created before invoking this method will use the domain's
187  * previous setting.
188  *
189  * @param[in] domain the ssl domain to configure.
190  * @param[in] mode the level of validation to apply to the peer
191  * @param[in] trusted_CAs path to a database of trusted CAs that the server will advertise
192  * to the peer client if the server has been configured to verify its peer.
193  * @return 0 on success
194  */
196  const pn_ssl_verify_mode_t mode,
197  const char *trusted_CAs);
198 
199 /** Permit a server to accept connection requests from non-SSL clients.
200  *
201  * This configures the server to "sniff" the incoming client data stream, and dynamically
202  * determine whether SSL/TLS is being used. This option is disabled by default: only
203  * clients using SSL/TLS are accepted.
204  *
205  * @param[in] domain the domain (server) that will accept the client connections.
206  * @return 0 on success
207  */
209 
210 /** Create a new SSL session object associated with a transport.
211  *
212  * A transport must have an SSL object in order to "speak" SSL over its connection. This
213  * method allocates an SSL object associates it with the transport.
214  *
215  * @param[in] transport the transport that will own the new SSL session.
216  * @return a pointer to the SSL object configured for this transport. Returns NULL if
217  * no SSL session is associated with the transport.
218  */
219 pn_ssl_t *pn_ssl(pn_transport_t *transport);
220 
221 /** Initialize an SSL session.
222  *
223  * This method configures an SSL object using the configuration provided by the given
224  * domain.
225  *
226  * @param[in] ssl the ssl session to configured.
227  * @param[in] domain the ssl domain used to configure the SSL session.
228  * @param[in] session_id if supplied, attempt to resume a previous SSL session that used
229  * the same session_id. The resulting session will be identified by the given session_id
230  * and stored for future session restore.
231  * @return 0 on success, else an error code.
232  */
233 int pn_ssl_init( pn_ssl_t *ssl,
234  pn_ssl_domain_t *domain,
235  const char *session_id);
236 
237 /** Get the name of the Cipher that is currently in use.
238  *
239  * Gets a text description of the cipher that is currently active, or returns FALSE if SSL
240  * is not active (no cipher). Note that the cipher in use may change over time due to
241  * renegotiation or other changes to the SSL state.
242  *
243  * @param[in] ssl the ssl client/server to query.
244  * @param[in,out] buffer buffer of size bytes to hold cipher name
245  * @param[in] size maximum number of bytes in buffer.
246  * @return True if cipher name written to buffer, False if no cipher in use.
247  */
248 bool pn_ssl_get_cipher_name(pn_ssl_t *ssl, char *buffer, size_t size);
249 
250 /** Get the name of the SSL protocol that is currently in use.
251  *
252  * Gets a text description of the SSL protocol that is currently active, or returns FALSE if SSL
253  * is not active. Note that the protocol may change over time due to renegotiation.
254  *
255  * @param[in] ssl the ssl client/server to query.
256  * @param[in,out] buffer buffer of size bytes to hold the version identifier
257  * @param[in] size maximum number of bytes in buffer.
258  * @return True if the version information was written to buffer, False if SSL connection
259  * not ready.
260  */
261 bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size);
262 
263 /** Check whether the state has been resumed.
264  *
265  * Used for client session resume. When called on an active session, indicates whether
266  * the state has been resumed from a previous session.
267  *
268  * @note This is a best-effort service - there is no guarantee that the remote server will
269  * accept the resumed parameters. The remote server may choose to ignore these
270  * parameters, and request a re-negotiation instead.
271  *
272  * @param[in] ssl the ssl session to check
273  * @return status code indicating whether or not the session has been resumed.
274  */
276 
277 /** Set the expected identity of the remote peer.
278  *
279  * The hostname is used for two purposes: 1) when set on an SSL client, it is sent to the
280  * server during the handshake (if Server Name Indication is supported), and 2) it is used
281  * to check against the identifying name provided in the peer's certificate. If the
282  * supplied name does not exactly match a SubjectAltName (type DNS name), or the
283  * CommonName entry in the peer's certificate, the peer is considered unauthenticated
284  * (potential imposter), and the SSL connection is aborted.
285  *
286  * @note Verification of the hostname is only done if PN_SSL_VERIFY_PEER_NAME is enabled.
287  * See ::pn_ssl_set_peer_authentication.
288  *
289  * @param[in] ssl the ssl session.
290  * @param[in] hostname the expected identity of the remote. Must conform to the syntax as
291  * given in RFC1034, Section 3.5.
292  * @return 0 on success.
293  */
294 int pn_ssl_set_peer_hostname( pn_ssl_t *ssl, const char *hostname);
295 
296 
297 /** Access the configured peer identity.
298  *
299  * Return the expected identity of the remote peer, as set by ::pn_ssl_set_peer_hostname.
300  *
301  * @param[in] ssl the ssl session.
302  * @param[out] hostname buffer to hold the null-terminated name string. If null, no string
303  * is written.
304  * @param[in,out] bufsize on input set to the number of octets in hostname. On output, set
305  * to the number of octets needed to hold the value of hostname plus a null byte. Zero if
306  * no hostname set.
307  * @return 0 on success.
308  */
309 int pn_ssl_get_peer_hostname( pn_ssl_t *ssl, char *hostname, size_t *bufsize );
310 
311 #ifdef __cplusplus
312 }
313 #endif
314 
315 #endif /* ssl.h */