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