00001 #ifndef PROTON_SSL_H 00002 #define PROTON_SSL_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <sys/types.h> 00027 #ifndef __cplusplus 00028 #include <stdbool.h> 00029 #endif 00030 #include <proton/engine.h> 00031 00032 #ifdef __cplusplus 00033 extern "C" { 00034 #endif 00035 00036 /** @file 00037 * API for using SSL with the Transport Layer. 00038 * 00039 * A Transport may be configured to use SSL for encryption and/or authentication. A 00040 * Transport can be configured as either an "SSL client" or an "SSL server". An SSL 00041 * client is the party that proactively establishes a connection to an SSL server. An SSL 00042 * server is the party that accepts a connection request from a remote SSL client. 00043 * 00044 * This SSL implementation defines the following objects: 00045 00046 * @li A top-level object that stores the configuration used by one or more SSL 00047 * sessions (pn_ssl_domain_t). 00048 * @li A per-connection SSL session object that performs the encryption/authentication 00049 * associated with the transport (pn_ssl_t). 00050 * @li The encryption parameters negotiated for the SSL session (pn_ssl_state_t). 00051 * 00052 * A pn_ssl_domain_t object must be created and configured before an SSL session can be 00053 * established. The pn_ssl_domain_t is used to construct an SSL session (pn_ssl_t). The 00054 * session "adopts" its configuration from the pn_ssl_domain_t that was used to create it. 00055 * For example, pn_ssl_domain_t can be configured as either a "client" or a "server". SSL 00056 * sessions constructed from this domain will perform the corresponding role (either 00057 * client or server). 00058 * 00059 * Some per-session attributes - such as peer verification mode - may be overridden on a 00060 * per-session basis from the default provided by the parent pn_ssl_domain_t. 00061 * 00062 * If either an SSL server or client needs to identify itself with the remote node, it 00063 * must have its SSL certificate configured (see ::pn_ssl_domain_set_credentials()). 00064 * 00065 * If either an SSL server or client needs to verify the identity of the remote node, it 00066 * must have its database of trusted CAs configured (see ::pn_ssl_domain_set_trusted_ca_db()). 00067 * 00068 * An SSL server connection may allow the remote client to connect without SSL (eg. "in 00069 * the clear"), see ::pn_ssl_allow_unsecured_client(). 00070 * 00071 * The level of verification required of the remote may be configured (see 00072 * ::pn_ssl_domain_set_default_peer_authentication ::pn_ssl_set_peer_authentication, 00073 * ::pn_ssl_get_peer_authentication). 00074 * 00075 * Support for SSL Client Session resume is provided (see ::pn_ssl_get_state, 00076 * ::pn_ssl_resume_state). 00077 */ 00078 00079 typedef struct pn_ssl_domain_t pn_ssl_domain_t; 00080 typedef struct pn_ssl_t pn_ssl_t; 00081 00082 /** Determines the type of SSL endpoint. */ 00083 typedef enum { 00084 PN_SSL_MODE_CLIENT=1, /**< Local connection endpoint is an SSL client */ 00085 PN_SSL_MODE_SERVER /**< Local connection endpoint is an SSL server */ 00086 } pn_ssl_mode_t; 00087 00088 /** Indicates whether an SSL session has been resumed. */ 00089 typedef enum { 00090 PN_SSL_RESUME_UNKNOWN, /**< Session resume state unknown/not supported */ 00091 PN_SSL_RESUME_NEW, /**< Session renegotiated - not resumed */ 00092 PN_SSL_RESUME_REUSED /**< Session resumed from previous session. */ 00093 } pn_ssl_resume_status_t; 00094 00095 /** Create an SSL configuration domain 00096 * 00097 * This method allocates an SSL domain object. This object is used to hold the SSL 00098 * configuration for one or more SSL sessions. The SSL session object (pn_ssl_t) is 00099 * allocated from this object. 00100 * 00101 * @param[in] mode the role, client or server, assumed by all SSL sessions created 00102 * with this domain. 00103 * @return a pointer to the SSL domain, if SSL support is present. 00104 */ 00105 PN_EXTERN pn_ssl_domain_t *pn_ssl_domain( pn_ssl_mode_t mode); 00106 00107 /** Release an SSL configuration domain 00108 * 00109 * This method frees an SSL domain object allocated by ::pn_ssl_domain. 00110 * @param[in] domain the domain to destroy. 00111 */ 00112 PN_EXTERN void pn_ssl_domain_free( pn_ssl_domain_t *domain ); 00113 00114 /** Set the certificate that identifies the local node to the remote. 00115 * 00116 * This certificate establishes the identity for the local node for all SSL sessions 00117 * created from this domain. It will be sent to the remote if the remote needs to verify 00118 * the identity of this node. This may be used for both SSL servers and SSL clients (if 00119 * client authentication is required by the server). 00120 * 00121 * @note This setting effects only those pn_ssl_t objects created after this call 00122 * returns. pn_ssl_t objects created before invoking this method will use the domain's 00123 * previous setting. 00124 * 00125 * @param[in] domain the ssl domain that will use this certificate. 00126 * @param[in] certificate_file path to file/database containing the identifying 00127 * certificate. 00128 * @param[in] private_key_file path to file/database containing the private key used to 00129 * sign the certificate 00130 * @param[in] password the password used to sign the key, else NULL if key is not 00131 * protected. 00132 * @return 0 on success 00133 */ 00134 PN_EXTERN int pn_ssl_domain_set_credentials( pn_ssl_domain_t *domain, 00135 const char *certificate_file, 00136 const char *private_key_file, 00137 const char *password); 00138 00139 /** Configure the set of trusted CA certificates used by this domain to verify peers. 00140 * 00141 * If the local SSL client/server needs to verify the identity of the remote, it must 00142 * validate the signature of the remote's certificate. This function sets the database of 00143 * trusted CAs that will be used to verify the signature of the remote's certificate. 00144 * 00145 * @note This setting effects only those pn_ssl_t objects created after this call 00146 * returns. pn_ssl_t objects created before invoking this method will use the domain's 00147 * previous setting. 00148 * 00149 * @param[in] domain the ssl domain that will use the database. 00150 * @param[in] certificate_db database of trusted CAs, used to authenticate the peer. 00151 * @return 0 on success 00152 */ 00153 PN_EXTERN int pn_ssl_domain_set_trusted_ca_db(pn_ssl_domain_t *domain, 00154 const char *certificate_db); 00155 00156 /** Determines the level of peer validation. 00157 * 00158 * ANONYMOUS_PEER does not require a valid certificate, and permits use of ciphers that 00159 * do not provide authentication. 00160 * 00161 * VERIFY_PEER will only connect to those peers that provide a valid identifying 00162 * certificate signed by a trusted CA and are using an authenticated cipher. 00163 * 00164 * VERIFY_PEER_NAME is like VERIFY_PEER, but also requires the peer's identity as 00165 * contained in the certificate to be valid (see ::pn_ssl_set_peer_hostname). 00166 * 00167 * ANONYMOUS_PEER is configured by default. 00168 */ 00169 typedef enum { 00170 PN_SSL_VERIFY_NULL=0, /**< internal use only */ 00171 PN_SSL_VERIFY_PEER, /**< require peer to provide a valid identifying certificate */ 00172 PN_SSL_ANONYMOUS_PEER, /**< do not require a certificate nor cipher authorization */ 00173 PN_SSL_VERIFY_PEER_NAME /**< require valid certificate and matching name */ 00174 } pn_ssl_verify_mode_t; 00175 00176 /** Configure the level of verification used on the peer certificate. 00177 * 00178 * This method controls how the peer's certificate is validated, if at all. By default, 00179 * neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER). 00180 * Once certificates and trusted CAs are configured, peer verification can be enabled. 00181 * 00182 * @note In order to verify a peer, a trusted CA must be configured. See 00183 * ::pn_ssl_set_trusted_ca_db(). 00184 * 00185 * @note Servers must provide their own certificate when verifying a peer. See 00186 * ::pn_ssl_set_credentials(). 00187 * 00188 * @note This setting effects only those pn_ssl_t objects created after this call 00189 * returns. pn_ssl_t objects created before invoking this method will use the domain's 00190 * previous setting. 00191 * 00192 * @param[in] domain the ssl domain to configure. 00193 * @param[in] mode the level of validation to apply to the peer 00194 * @param[in] trusted_CAs path to a database of trusted CAs that the server will advertise 00195 * to the peer client if the server has been configured to verify its peer. 00196 * @return 0 on success 00197 */ 00198 PN_EXTERN int pn_ssl_domain_set_peer_authentication(pn_ssl_domain_t *domain, 00199 const pn_ssl_verify_mode_t mode, 00200 const char *trusted_CAs); 00201 00202 /** Permit a server to accept connection requests from non-SSL clients. 00203 * 00204 * This configures the server to "sniff" the incoming client data stream, and dynamically 00205 * determine whether SSL/TLS is being used. This option is disabled by default: only 00206 * clients using SSL/TLS are accepted. 00207 * 00208 * @param[in] domain the domain (server) that will accept the client connections. 00209 * @return 0 on success 00210 */ 00211 PN_EXTERN int pn_ssl_domain_allow_unsecured_client(pn_ssl_domain_t *domain); 00212 00213 /** Create a new SSL session object associated with a transport. 00214 * 00215 * A transport must have an SSL object in order to "speak" SSL over its connection. This 00216 * method allocates an SSL object associates it with the transport. 00217 * 00218 * @param[in] transport the transport that will own the new SSL session. 00219 * @return a pointer to the SSL object configured for this transport. Returns NULL if 00220 * no SSL session is associated with the transport. 00221 */ 00222 PN_EXTERN pn_ssl_t *pn_ssl(pn_transport_t *transport); 00223 00224 /** Initialize an SSL session. 00225 * 00226 * This method configures an SSL object using the configuration provided by the given 00227 * domain. 00228 * 00229 * @param[in] ssl the ssl session to configured. 00230 * @param[in] domain the ssl domain used to configure the SSL session. 00231 * @param[in] session_id if supplied, attempt to resume a previous SSL session that used 00232 * the same session_id. The resulting session will be identified by the given session_id 00233 * and stored for future session restore. 00234 * @return 0 on success, else an error code. 00235 */ 00236 PN_EXTERN int pn_ssl_init( pn_ssl_t *ssl, 00237 pn_ssl_domain_t *domain, 00238 const char *session_id); 00239 00240 /** Get the name of the Cipher that is currently in use. 00241 * 00242 * Gets a text description of the cipher that is currently active, or returns FALSE if SSL 00243 * is not active (no cipher). Note that the cipher in use may change over time due to 00244 * renegotiation or other changes to the SSL state. 00245 * 00246 * @param[in] ssl the ssl client/server to query. 00247 * @param[in,out] buffer buffer of size bytes to hold cipher name 00248 * @param[in] size maximum number of bytes in buffer. 00249 * @return True if cipher name written to buffer, False if no cipher in use. 00250 */ 00251 PN_EXTERN bool pn_ssl_get_cipher_name(pn_ssl_t *ssl, char *buffer, size_t size); 00252 00253 /** Get the name of the SSL protocol that is currently in use. 00254 * 00255 * Gets a text description of the SSL protocol that is currently active, or returns FALSE if SSL 00256 * is not active. Note that the protocol may change over time due to renegotiation. 00257 * 00258 * @param[in] ssl the ssl client/server to query. 00259 * @param[in,out] buffer buffer of size bytes to hold the version identifier 00260 * @param[in] size maximum number of bytes in buffer. 00261 * @return True if the version information was written to buffer, False if SSL connection 00262 * not ready. 00263 */ 00264 PN_EXTERN bool pn_ssl_get_protocol_name(pn_ssl_t *ssl, char *buffer, size_t size); 00265 00266 /** Check whether the state has been resumed. 00267 * 00268 * Used for client session resume. When called on an active session, indicates whether 00269 * the state has been resumed from a previous session. 00270 * 00271 * @note This is a best-effort service - there is no guarantee that the remote server will 00272 * accept the resumed parameters. The remote server may choose to ignore these 00273 * parameters, and request a re-negotiation instead. 00274 * 00275 * @param[in] ssl the ssl session to check 00276 * @return status code indicating whether or not the session has been resumed. 00277 */ 00278 PN_EXTERN pn_ssl_resume_status_t pn_ssl_resume_status( pn_ssl_t *ssl ); 00279 00280 /** Set the expected identity of the remote peer. 00281 * 00282 * The hostname is used for two purposes: 1) when set on an SSL client, it is sent to the 00283 * server during the handshake (if Server Name Indication is supported), and 2) it is used 00284 * to check against the identifying name provided in the peer's certificate. If the 00285 * supplied name does not exactly match a SubjectAltName (type DNS name), or the 00286 * CommonName entry in the peer's certificate, the peer is considered unauthenticated 00287 * (potential imposter), and the SSL connection is aborted. 00288 * 00289 * @note Verification of the hostname is only done if PN_SSL_VERIFY_PEER_NAME is enabled. 00290 * See ::pn_ssl_set_peer_authentication. 00291 * 00292 * @param[in] ssl the ssl session. 00293 * @param[in] hostname the expected identity of the remote. Must conform to the syntax as 00294 * given in RFC1034, Section 3.5. 00295 * @return 0 on success. 00296 */ 00297 PN_EXTERN int pn_ssl_set_peer_hostname( pn_ssl_t *ssl, const char *hostname); 00298 00299 00300 /** Access the configured peer identity. 00301 * 00302 * Return the expected identity of the remote peer, as set by ::pn_ssl_set_peer_hostname. 00303 * 00304 * @param[in] ssl the ssl session. 00305 * @param[out] hostname buffer to hold the null-terminated name string. If null, no string 00306 * is written. 00307 * @param[in,out] bufsize on input set to the number of octets in hostname. On output, set 00308 * to the number of octets needed to hold the value of hostname plus a null byte. Zero if 00309 * no hostname set. 00310 * @return 0 on success. 00311 */ 00312 PN_EXTERN int pn_ssl_get_peer_hostname( pn_ssl_t *ssl, char *hostname, size_t *bufsize ); 00313 00314 #ifdef __cplusplus 00315 } 00316 #endif 00317 00318 #endif /* ssl.h */