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