proton  0
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/types.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 /** Tests for SSL implementation present
94  *
95  * @return true if we support SSL, false if not
96  */
97 PN_EXTERN bool pn_ssl_present( void );
98 
99 /** Create an SSL configuration domain
100  *
101  * This method allocates an SSL domain object. This object is used to hold the SSL
102  * configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is
103  * allocated from this object.
104  *
105  * @param[in] mode the role, client or server, assumed by all SSL sessions created
106  * with this domain.
107  * @return a pointer to the SSL domain, if SSL support is present.
108  */
110 
111 /** Release an SSL configuration domain
112  *
113  * This method frees an SSL domain object allocated by ::pn_ssl_domain.
114  * @param[in] domain the domain to destroy.
115  */
117 
118 /** Set the certificate that identifies the local node to the remote.
119  *
120  * This certificate establishes the identity for the local node for all SSL sessions
121  * created from this domain. It will be sent to the remote if the remote needs to verify
122  * the identity of this node. This may be used for both SSL servers and SSL clients (if
123  * client authentication is required by the server).
124  *
125  * @note This setting effects only those pn_ssl_t objects created after this call
126  * returns. pn_ssl_t objects created before invoking this method will use the domain's
127  * previous setting.
128  *
129  * @param[in] domain the ssl domain that will use this certificate.
130  * @param[in] credential_1 specifier for the file/database containing the identifying
131  * certificate. For Openssl users, this is a PEM file. For Windows SChannel users, this is
132  * the PKCS#12 file or system store.
133  * @param[in] credential_2 an optional key to access the identifying certificate. For
134  * Openssl users, this is an optional PEM file containing the private key used to sign the
135  * certificate. For Windows SChannel users, this is the friendly name of the
136  * self-identifying certificate if there are multiple certificates in the store.
137  * @param[in] password the password used to sign the key, else NULL if key is not
138  * protected.
139  * @return 0 on success
140  */
142  const char *credential_1,
143  const char *credential_2,
144  const char *password);
145 
146 /** Configure the set of trusted CA certificates used by this domain to verify peers.
147  *
148  * If the local SSL client/server needs to verify the identity of the remote, it must
149  * validate the signature of the remote's certificate. This function sets the database of
150  * trusted CAs that will be used to verify the signature of the remote's certificate.
151  *
152  * @note This setting effects only those pn_ssl_t objects created after this call
153  * returns. pn_ssl_t objects created before invoking this method will use the domain's
154  * previous setting.
155  *
156  * @param[in] domain the ssl domain that will use the database.
157  * @param[in] certificate_db database of trusted CAs, used to authenticate the peer.
158  * @return 0 on success
159  */
161  const char *certificate_db);
162 
163 /** Determines the level of peer validation.
164  *
165  * ANONYMOUS_PEER does not require a valid certificate, and permits use of ciphers that
166  * do not provide authentication.
167  *
168  * VERIFY_PEER will only connect to those peers that provide a valid identifying
169  * certificate signed by a trusted CA and are using an authenticated cipher.
170  *
171  * VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's identity as
172  * contained in the certificate to be valid (see ::pn_ssl_set_peer_hostname).
173  *
174  * ANONYMOUS_PEER is configured by default.
175  */
176 typedef enum {
177  PN_SSL_VERIFY_NULL=0, /**< internal use only */
178  PN_SSL_VERIFY_PEER, /**< require peer to provide a valid identifying certificate */
179  PN_SSL_ANONYMOUS_PEER, /**< do not require a certificate nor cipher authorization */
180  PN_SSL_VERIFY_PEER_NAME /**< require valid certificate and matching name */
182 
183 /** Configure the level of verification used on the peer certificate.
184  *
185  * This method controls how the peer's certificate is validated, if at all. By default,
186  * neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER).
187  * Once certificates and trusted CAs are configured, peer verification can be enabled.
188  *
189  * @note In order to verify a peer, a trusted CA must be configured. See
190  * ::pn_ssl_domain_set_trusted_ca_db().
191  *
192  * @note Servers must provide their own certificate when verifying a peer. See
193  * ::pn_ssl_domain_set_credentials().
194  *
195  * @note This setting effects only those pn_ssl_t objects created after this call
196  * returns. pn_ssl_t objects created before invoking this method will use the domain's
197  * previous setting.
198  *
199  * @param[in] domain the ssl domain to configure.
200  * @param[in] mode the level of validation to apply to the peer
201  * @param[in] trusted_CAs path to a database of trusted CAs that the server will advertise
202  * to the peer client if the server has been configured to verify its peer.
203  * @return 0 on success
204  */
206  const pn_ssl_verify_mode_t mode,
207  const char *trusted_CAs);
208 
209 /** Permit a server to accept connection requests from non-SSL clients.
210  *
211  * This configures the server to "sniff" the incoming client data stream, and dynamically
212  * determine whether SSL/TLS is being used. This option is disabled by default: only
213  * clients using SSL/TLS are accepted.
214  *
215  * @param[in] domain the domain (server) that will accept the client connections.
216  * @return 0 on success
217  */
219 
220 /** Create a new SSL session object associated with a transport.
221  *
222  * A transport must have an SSL object in order to "speak" SSL over its connection. This
223  * method allocates an SSL object associates it with the transport.
224  *
225  * @param[in] transport the transport that will own the new SSL session.
226  * @return a pointer to the SSL object configured for this transport. Returns NULL if
227  * no SSL session is associated with the transport.
228  */
230 
231 /** Initialize an SSL session.
232  *
233  * This method configures an SSL object using the configuration provided by the given
234  * domain.
235  *
236  * @param[in] ssl the ssl session to configured.
237  * @param[in] domain the ssl domain used to configure the SSL session.
238  * @param[in] session_id if supplied, attempt to resume a previous SSL
239  * session that used the same session_id. If no previous SSL session
240  * is available, a new session will be created using the session_id
241  * and stored for future session restore (see ::::pn_ssl_resume_status).
242  * @return 0 on success, else an error code.
243  */
244 PN_EXTERN int pn_ssl_init( pn_ssl_t *ssl,
245  pn_ssl_domain_t *domain,
246  const char *session_id);
247 
248 /** Get the name of the Cipher that is currently in use.
249  *
250  * Gets a text description of the cipher that is currently active, or returns FALSE if SSL
251  * is not active (no cipher). Note that the cipher in use may change over time due to
252  * renegotiation or other changes to the SSL state.
253  *
254  * @param[in] ssl the ssl client/server to query.
255  * @param[in,out] buffer buffer of size bytes to hold cipher name
256  * @param[in] size maximum number of bytes in buffer.
257  * @return True if cipher name written to buffer, False if no cipher in use.
258  */
259 PN_EXTERN bool pn_ssl_get_cipher_name(pn_ssl_t *ssl, char *buffer, size_t size);
260 
261 /** Get the name of the SSL protocol that is currently in use.
262  *
263  * Gets a text description of the SSL protocol that is currently active, or returns FALSE if SSL
264  * is not active. Note that the protocol may change over time due to renegotiation.
265  *
266  * @param[in] ssl the ssl client/server to query.
267  * @param[in,out] buffer buffer of size bytes to hold the version identifier
268  * @param[in] size maximum number of bytes in buffer.
269  * @return True if the version information was written to buffer, False if SSL connection
270  * not ready.
271  */
272 PN_EXTERN bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size);
273 
274 /** Check whether the state has been resumed.
275  *
276  * Used for client session resume. When called on an active session, indicates whether
277  * the state has been resumed from a previous session.
278  *
279  * @note This is a best-effort service - there is no guarantee that the remote server will
280  * accept the resumed parameters. The remote server may choose to ignore these
281  * parameters, and request a re-negotiation instead.
282  *
283  * @param[in] ssl the ssl session to check
284  * @return status code indicating whether or not the session has been resumed.
285  */
287 
288 /** Set the expected identity of the remote peer.
289  *
290  * The hostname is used for two purposes: 1) when set on an SSL client, it is sent to the
291  * server during the handshake (if Server Name Indication is supported), and 2) it is used
292  * to check against the identifying name provided in the peer's certificate. If the
293  * supplied name does not exactly match a SubjectAltName (type DNS name), or the
294  * CommonName entry in the peer's certificate, the peer is considered unauthenticated
295  * (potential imposter), and the SSL connection is aborted.
296  *
297  * @note Verification of the hostname is only done if PN_SSL_VERIFY_PEER_NAME is enabled.
298  * See ::pn_ssl_domain_set_peer_authentication.
299  *
300  * @param[in] ssl the ssl session.
301  * @param[in] hostname the expected identity of the remote. Must conform to the syntax as
302  * given in RFC1034, Section 3.5.
303  * @return 0 on success.
304  */
305 PN_EXTERN int pn_ssl_set_peer_hostname( pn_ssl_t *ssl, const char *hostname);
306 
307 
308 /** Access the configured peer identity.
309  *
310  * Return the expected identity of the remote peer, as set by ::pn_ssl_set_peer_hostname.
311  *
312  * @param[in] ssl the ssl session.
313  * @param[out] hostname buffer to hold the null-terminated name string. If null, no string
314  * is written.
315  * @param[in,out] bufsize on input set to the number of octets in hostname. On output, set
316  * to the number of octets needed to hold the value of hostname plus a null byte. Zero if
317  * no hostname set.
318  * @return 0 on success.
319  */
320 PN_EXTERN int pn_ssl_get_peer_hostname( pn_ssl_t *ssl, char *hostname, size_t *bufsize );
321 
322 /** @} */
323 
324 #ifdef __cplusplus
325 }
326 #endif
327 
328 #endif /* ssl.h */
pn_ssl_mode_t
Determines the type of SSL endpoint.
Definition: ssl.h:81
PN_EXTERN int pn_ssl_domain_set_credentials(pn_ssl_domain_t *domain, const char *credential_1, const char *credential_2, const char *password)
Set the certificate that identifies the local node to the remote.
PN_EXTERN void pn_ssl_domain_free(pn_ssl_domain_t *domain)
Release an SSL configuration domain.
internal use only
Definition: ssl.h:177
do not require a certificate nor cipher authorization
Definition: ssl.h:179
PN_EXTERN pn_ssl_domain_t * pn_ssl_domain(pn_ssl_mode_t mode)
Create an SSL configuration domain.
pn_ssl_resume_status_t
Indicates whether an SSL session has been resumed.
Definition: ssl.h:87
Session resumed from previous session.
Definition: ssl.h:90
PN_EXTERN int pn_ssl_domain_set_peer_authentication(pn_ssl_domain_t *domain, const pn_ssl_verify_mode_t mode, const char *trusted_CAs)
Configure the level of verification used on the peer certificate.
struct pn_ssl_t pn_ssl_t
Definition: ssl.h:78
PN_EXTERN int pn_ssl_domain_allow_unsecured_client(pn_ssl_domain_t *domain)
Permit a server to accept connection requests from non-SSL clients.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN int pn_ssl_domain_set_trusted_ca_db(pn_ssl_domain_t *domain, const char *certificate_db)
Configure the set of trusted CA certificates used by this domain to verify peers. ...
require peer to provide a valid identifying certificate
Definition: ssl.h:178
Session resume state unknown/not supported.
Definition: ssl.h:88
PN_EXTERN int pn_ssl_get_peer_hostname(pn_ssl_t *ssl, char *hostname, size_t *bufsize)
Access the configured peer identity.
require valid certificate and matching name
Definition: ssl.h:180
pn_ssl_verify_mode_t
Determines the level of peer validation.
Definition: ssl.h:176
Session renegotiated - not resumed.
Definition: ssl.h:89
PN_EXTERN int pn_ssl_set_peer_hostname(pn_ssl_t *ssl, const char *hostname)
Set the expected identity of the remote peer.
struct pn_ssl_domain_t pn_ssl_domain_t
Definition: ssl.h:77
PN_EXTERN int pn_ssl_init(pn_ssl_t *ssl, pn_ssl_domain_t *domain, const char *session_id)
Initialize an SSL session.
Local connection endpoint is an SSL server.
Definition: ssl.h:83
Local connection endpoint is an SSL client.
Definition: ssl.h:82
PN_EXTERN bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size)
Get the name of the SSL protocol that is currently in use.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:256
PN_EXTERN bool pn_ssl_get_cipher_name(pn_ssl_t *ssl, char *buffer, size_t size)
Get the name of the Cipher that is currently in use.
PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status(pn_ssl_t *ssl)
Check whether the state has been resumed.
PN_EXTERN bool pn_ssl_present(void)
Tests for SSL implementation present.
PN_EXTERN pn_ssl_t * pn_ssl(pn_transport_t *transport)
Create a new SSL session object associated with a transport.