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