diff options
Diffstat (limited to 'doc/ssl')
79 files changed, 6892 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod new file mode 100644 index 000000000000..f81f692df5de --- /dev/null +++ b/doc/ssl/SSL_CIPHER_get_name.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); + int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); + char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); + char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size); + +=head1 DESCRIPTION + +SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the +argument is the NULL pointer, a pointer to the constant value "NONE" is +returned. + +SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If +B<alg_bits> is not NULL, it contains the number of bits processed by the +chosen algorithm. If B<cipher> is NULL, 0 is returned. + +SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently +"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned. + +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B<buf> of length B<len> provided. B<len> must be at least +128 bytes, otherwise a pointer to the the string "Buffer too small" is +returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using +OPENSSL_malloc(). If the allocation fails, a pointer to the string +"OPENSSL_malloc Error" is returned. + +=head1 NOTES + +The number of bits processed can be different from the secret bits. An +export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm +does use the full 128 bits (which would be returned for B<alg_bits>), of +which however 88bits are fixed. The search space is hence only 40 bits. + +The string returned by SSL_CIPHER_description() in case of success consists +of cleartext information separated by one or more blanks in the following +sequence: + +=over 4 + +=item <ciphername> + +Textual representation of the cipher name. + +=item <protocol version> + +Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3. + +=item Kx=<key exchange> + +Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or +B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>), +B<DH/RSA>, B<DH/DSS>, B<Fortezza>. + +=item Au=<authentication> + +Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the +representation of anonymous ciphers. + +=item Enc=<symmetric encryption method> + +Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>, +B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>, +B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>. + +=item Mac=<message authentication code> + +Message digest: B<MD5>, B<SHA1>. + +=item <export flag> + +If the cipher is flagged exportable with respect to old US crypto +regulations, the word "B<export>" is printed. + +=back + +=head1 EXAMPLES + +Some examples for the output of SSL_CIPHER_description(): + + EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 + EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 + RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 + EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export + +=head1 BUGS + +If SSL_CIPHER_description() is called with B<cipher> being NULL, the +library crashes. + +If SSL_CIPHER_description() cannot handle a built-in cipher, the according +description of the cipher property is B<unknown>. This case should not +occur. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, +L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)> + +=cut diff --git a/doc/ssl/SSL_COMP_add_compression_method.pod b/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 000000000000..42fa66b19751 --- /dev/null +++ b/doc/ssl/SSL_COMP_add_compression_method.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SSL_COMP_add_compression_method - handle SSL/TLS integrated compression methods + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); + +=head1 DESCRIPTION + +SSL_COMP_add_compression_method() adds the compression method B<cm> with +the identifier B<id> to the list of available compression methods. This +list is globally maintained for all SSL operations within this application. +It cannot be set for specific SSL_CTX or SSL objects. + +=head1 NOTES + +The TLS standard (or SSLv3) allows the integration of compression methods +into the communication. The TLS RFC does however not specify compression +methods or their corresponding identifiers, so there is currently no compatible +way to integrate compression with unknown peers. It is therefore currently not +recommended to integrate compression into applications. Applications for +non-public use may agree on certain compression methods. Using different +compression methods with the same identifier will lead to connection failure. + +An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) +will unconditionally send the list of all compression methods enabled with +SSL_COMP_add_compression_method() to the server during the handshake. +Unlike the mechanisms to set a cipher list, there is no method available to +restrict the list of compression method on a per connection basis. + +An OpenSSL server will match the identifiers listed by a client against +its own compression methods and will unconditionally activate compression +when a matching identifier is found. There is no way to restrict the list +of compression methods supported on a per connection basis. + +The OpenSSL library has the compression methods B<COMP_rle()> and (when +especially enabled during compilation) B<COMP_zlib()> available. + +=head1 WARNINGS + +Once the identities of the compression methods for the TLS protocol have +been standardized, the compression API will most likely be changed. Using +it in the current state is not recommended. + +=head1 RETURN VALUES + +SSL_COMP_add_compression_method() may return the following values: + +=over 4 + +=item 0 + +The operation succeeded. + +=item 1 + +The operation failed. Check the error queue to find out the reason. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod new file mode 100644 index 000000000000..ee28f5ccc3a3 --- /dev/null +++ b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_CTX_add_extra_chain_cert - add certificate to chain + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509) + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate +chain presented together with the certificate. Several certificates +can be added one after the other. + +=head1 NOTES + +When constructing the certificate chain, the chain will be formed from +these certificates explicitly specified. If no chain is specified, +the library will try to complete the chain from the available CA +certificates in the trusted CA storage, see +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. + +=head1 RETURN VALUES + +SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the +error stack to find out the reason for failure otherwise. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_add_session.pod b/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 000000000000..82676b26b239 --- /dev/null +++ b/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); + + int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + +=head1 DESCRIPTION + +SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The +reference count for session B<c> is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. + +SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>. + +SSL_add_session() and SSL_remove_session() are synonyms for their +SSL_CTX_*() counterparts. + +=head1 NOTES + +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. In this case +it is assumed that both sessions are identical. If the same session is +stored in a different SSL_SESSION object, The old session is +removed and replaced by the new session. If the session is actually +identical (the SSL_SESSION object is identical), SSL_CTX_add_session() +is a no-op, and the return value is 0. + +If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE +flag then the internal cache will not be populated automatically by new +sessions negotiated by the SSL/TLS implementation, even though the internal +cache will be searched automatically for session-resume requests (the +latter can be surpressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the +application can use SSL_CTX_add_session() directly to have full control +over the sessions that can be resumed if desired. + + +=head1 RETURN VALUES + +The following values are returned by all functions: + +=over 4 + +=item 0 + + The operation failed. In case of the add operation, it was tried to add + the same (identical) session twice. In case of the remove operation, the + session was not found in the cache. + +=item 1 + + The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_ctrl.pod b/doc/ssl/SSL_CTX_ctrl.pod new file mode 100644 index 000000000000..fb6adcf50c16 --- /dev/null +++ b/doc/ssl/SSL_CTX_ctrl.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg); + long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); + + long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); + long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); + +=head1 DESCRIPTION + +The SSL_*_ctrl() family of functions is used to manipulate settings of +the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments +B<larg>, B<parg>, or B<fp> are evaluated. These functions should never +be called directly. All functionalities needed are made available via +other functions or macros. + +=head1 RETURN VALUES + +The return values of the SSL*_ctrl() functions depend on the command +supplied via the B<cmd> parameter. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_flush_sessions.pod b/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 000000000000..148c36c87151 --- /dev/null +++ b/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); + void SSL_flush_sessions(SSL_CTX *ctx, long tm); + +=head1 DESCRIPTION + +SSL_CTX_flush_sessions() causes a run through the session cache of +B<ctx> to remove sessions expired at time B<tm>. + +SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). + +=head1 NOTES + +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see SSL_CTX_sess_set_cache_size()). +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. This can either be done + automatically whenever 255 new sessions were established (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B<tm> specifies the time which should be used for the +expiration test, in most cases the actual time given by time(0) +will be used. + +SSL_CTX_flush_sessions() will only check sessions stored in the internal +cache. When a session is found and removed, the remove_session_cb is however +called to synchronize with the external cache (see +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). + +=head1 RETURN VALUES + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_free.pod b/doc/ssl/SSL_CTX_free.pod new file mode 100644 index 000000000000..51d86769682f --- /dev/null +++ b/doc/ssl/SSL_CTX_free.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +SSL_CTX_free - free an allocated SSL_CTX object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_free(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_free() decrements the reference count of B<ctx>, and removes the +SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the +the reference count has reached 0. + +It also calls the free()ing procedures for indirectly affected items, if +applicable: the session cache, the list of ciphers, the list of Client CAs, +the certificates and keys. + +=head1 WARNINGS + +If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this +callback will be called for each session being freed from B<ctx>'s +session cache. This implies, that all corresponding sessions from an +external session cache are removed as well. If this is not desired, the user +should explicitly unset the callback by calling +SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free(). + +=head1 RETURN VALUES + +SSL_CTX_free() does not provide diagnostic information. + +=head1 SEE ALSO + +L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_get_ex_new_index.pod b/doc/ssl/SSL_CTX_get_ex_new_index.pod new file mode 100644 index 000000000000..0c40a91f2fb3 --- /dev/null +++ b/doc/ssl/SSL_CTX_get_ex_new_index.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); + + void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_CTX_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx> +into the B<ctx> object. + +SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from +B<ctx>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_get_verify_mode.pod b/doc/ssl/SSL_CTX_get_verify_mode.pod new file mode 100644 index 000000000000..2a3747e75c64 --- /dev/null +++ b/doc/ssl/SSL_CTX_get_verify_mode.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); + int SSL_get_verify_mode(const SSL *ssl); + int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); + int SSL_get_verify_depth(const SSL *ssl); + int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *); + int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *); + +=head1 DESCRIPTION + +SSL_CTX_get_verify_mode() returns the verification mode currently set in +B<ctx>. + +SSL_get_verify_mode() returns the verification mode currently set in +B<ssl>. + +SSL_CTX_get_verify_depth() returns the verification depth limit currently set +in B<ctx>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_get_verify_depth() returns the verification depth limit currently set +in B<ssl>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_CTX_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ctx>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +SSL_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ssl>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 000000000000..84a799fc71dd --- /dev/null +++ b/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +SSL_CTX_load_verify_locations - set default locations for trusted CA +certificates + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, + const char *CApath); + +=head1 DESCRIPTION + +SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at +which CA certificates for verification purposes are located. The certificates +available via B<CAfile> and B<CApath> are trusted. + +=head1 NOTES + +If B<CAfile> is not NULL, it points to a file of CA certificates in PEM +format. The file can contain several CA certificates identified by + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + +sequences. Before, between, and after the certificates text is allowed +which can be used e.g. for descriptions of the certificates. + +The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() +function. + +If B<CApath> is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain one CA certificate. The files are +looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. +Use the B<c_rehash> utility to create the necessary links. + +The certificates in B<CApath> are only looked up when required, e.g. when +building the certificate chain or when actually performing the verification +of a peer certificate. + +When looking up CA certificates, the OpenSSL library will first search the +certificates in B<CAfile>, then those in B<CApath>. Certificate matching +is done based on the subject name, the key identifier (if present), and the +serial number as taken from the certificate to be verified. If these data +do not match, the next certificate will be tried. If a first certificate +matching the parameters is found, the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. + +In server mode, when requesting a client certificate, the server must send +the list of CAs of which it will accept client certificates. This list +is not influenced by the contents of B<CAfile> or B<CApath> and must +explicitly be set using the +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> +family of functions. + +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from B<CAfile>/B<CApath>, if the +certificate chain was not explicitly specified (see +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>. + +=head1 WARNINGS + +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. + +=head1 EXAMPLES + +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: + + #!/bin/sh + rm CAfile.pem + for i in ca1.pem ca2.pem ca3.pem ; do + openssl x509 -in $i -text >> CAfile.pem + done + +Prepare the directory /some/where/certs containing several CA certificates +for use as B<CApath>: + + cd /some/where/certs + c_rehash . + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed because B<CAfile> and B<CApath> are NULL or the +processing at one of the locations specified failed. Check the error +stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod new file mode 100644 index 000000000000..465220a75c0a --- /dev/null +++ b/doc/ssl/SSL_CTX_new.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CTX *SSL_CTX_new(SSL_METHOD *method); + +=head1 DESCRIPTION + +SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish +TLS/SSL enabled connections. + +=head1 NOTES + +The SSL_CTX object uses B<method> as connection method. The methods exist +in a generic type (for client and server use), a server only type, and a +client only type. B<method> can be of the following types: + +=over 4 + +=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void) + +A TLS/SSL connection established with these methods will only understand +the SSLv2 protocol. A client will send out SSLv2 client hello messages +and will also indicate that it only understand SSLv2. A server will only +understand SSLv2 client hello messages. + +=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) + +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. A client will send out SSLv3 client hello messages +and will indicate that it only understands SSLv3. A server will only understand +SSLv3 client hello messages. This especially means, that it will +not understand SSLv2 client hello messages which are widely used for +compatibility reasons, see SSLv23_*_method(). + +=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) + +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. A client will send out TLSv1 client hello messages +and will indicate that it only understands TLSv1. A server will only understand +TLSv1 client hello messages. This especially means, that it will +not understand SSLv2 client hello messages which are widely used for +compatibility reasons, see SSLv23_*_method(). It will also not understand +SSLv3 client hello messages. + +=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) + +A TLS/SSL connection established with these methods will understand the SSLv2, +SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages +and will indicate that it also understands SSLv3 and TLSv1. A server will +understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best +choice when compatibility is a concern. + +=back + +The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, +SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or +B<SSL_set_options()> functions. Using these options it is possible to choose +e.g. SSLv23_server_method() and be able to negotiate with all possible +clients, but to only allow newer protocols like SSLv3 or TLSv1. + +SSL_CTX_new() initializes the list of ciphers, the session cache setting, +the callbacks, the keys and certificates, and the options to its default +values. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL_CTX object failed. Check the error stack to +find out the reason. + +=item Pointer to an SSL_CTX object + +The return value points to an allocated SSL_CTX object. + +=back + +=head1 SEE ALSO + +L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sess_number.pod b/doc/ssl/SSL_CTX_sess_number.pod new file mode 100644 index 000000000000..19aa4e29027b --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_number.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_number(SSL_CTX *ctx); + long SSL_CTX_sess_connect(SSL_CTX *ctx); + long SSL_CTX_sess_connect_good(SSL_CTX *ctx); + long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx); + long SSL_CTX_sess_accept(SSL_CTX *ctx); + long SSL_CTX_sess_accept_good(SSL_CTX *ctx); + long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx); + long SSL_CTX_sess_hits(SSL_CTX *ctx); + long SSL_CTX_sess_cb_hits(SSL_CTX *ctx); + long SSL_CTX_sess_misses(SSL_CTX *ctx); + long SSL_CTX_sess_timeouts(SSL_CTX *ctx); + long SSL_CTX_sess_cache_full(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_number() returns the current number of sessions in the internal +session cache. + +SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in +client mode. + +SSL_CTX_sess_connect_good() returns the number of successfully established +SSL/TLS sessions in client mode. + +SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations +in client mode. + +SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in +server mode. + +SSL_CTX_sess_accept_good() returns the number of successfully established +SSL/TLS sessions in server mode. + +SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations +in server mode. + +SSL_CTX_sess_hits() returns the number of successfully reused sessions. +In client mode a session set with L<SSL_set_session(3)|SSL_set_session(3)> +successfully reused is counted as a hit. In server mode a session successfully +retrieved from internal or external cache is counted as a hit. + +SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions +from the external session cache in server mode. + +SSL_CTX_sess_misses() returns the number of sessions proposed by clients +that were not found in the internal session cache in server mode. + +SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients +and either found in the internal or external session cache in server mode, + but that were invalid due to timeout. These sessions are not included in +the SSL_CTX_sess_hits() count. + +SSL_CTX_sess_cache_full() returns the number of sessions that were removed +because the maximum session cache size was exceeded. + +=head1 RETURN VALUES + +The functions return the values indicated in the DESCRIPTION section. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> +L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 000000000000..c8b99f4eef09 --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); + long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_cache_size() sets the size of the internal session cache +of context B<ctx> to B<t>. + +SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. + +=head1 NOTES + +The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, +currently 1024*20, so that up to 20000 sessions can be held. This size +can be modified using the SSL_CTX_sess_set_cache_size() call. A special +case is the size 0, which is used for unlimited size. + +When the maximum number of sessions is reached, no more new sessions are +added to the cache. New space may be added by calling +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> to remove +expired sessions. + +If the size of the session cache is reduced and more sessions are already +in the session cache, old session will be removed at the next time a +session shall be added. This removal is not synchronized with the +expiration of sessions. + +=head1 RETURN VALUES + +SSL_CTX_sess_set_cache_size() returns the previously valid size. + +SSL_CTX_sess_get_cache_size() returns the currently valid size. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 000000000000..b9d54a40a193 --- /dev/null +++ b/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, + int (*new_session_cb)(SSL *, SSL_SESSION *)); + void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, + void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); + void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, + SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); + + int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); + void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); + + int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); + void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, + int len, int *copy); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically +called whenever a new session was negotiated. + +SSL_CTX_sess_set_remove_cb() sets the callback function, which is +automatically called whenever a session is removed by the SSL engine, +because it is considered faulty or the session has become obsolete because +of exceeding the timeout value. + +SSL_CTX_sess_set_get_cb() sets the callback function which is called, +whenever a SSL/TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +(SSL/TLS server only.) + +SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and +SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the +provided callback functions. If a callback function has not been set, +the NULL pointer is returned. + +=head1 NOTES + +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. Inside these callback +functions, session can be saved to disk or put into a database using the +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +The new_session_cb() is passed the B<ssl> connection and the ssl session +B<sess>. If the callback returns B<0>, the session will be immediately +removed again. + +The remove_session_cb() is called, whenever the SSL engine removes a session +from the internal cache. This happens when the session is removed because +it is expired or when a connection was not shutdown cleanly. It also happens +for all sessions in the internal session cache when +L<SSL_CTX_free(3)|SSL_CTX_free(3)> is called. The remove_session_cb() is passed +the B<ctx> and the ssl session B<sess>. It does not provide any feedback. + +The get_session_cb() is only called on SSL/TLS servers with the session id +proposed by the client. The get_session_cb() is always called, also when +session caching was disabled. The get_session_cb() is passed the +B<ssl> connection, the session id of length B<length> at the memory location +B<data>. With the parameter B<copy> the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object, +Normally the reference count is not incremented and therefore the +session must not be explicitly freed with +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_CTX_free(3)|SSL_CTX_free(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_sessions.pod b/doc/ssl/SSL_CTX_sessions.pod new file mode 100644 index 000000000000..e05aab3c1bc2 --- /dev/null +++ b/doc/ssl/SSL_CTX_sessions.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_CTX_sessions - access internal session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sessions() returns a pointer to the lhash databases containing the +internal session cache for B<ctx>. + +=head1 NOTES + +The sessions in the internal session cache are kept in an +L<lhash(3)|lhash(3)> type database. It is possible to directly +access this database e.g. for searching. In parallel, the sessions +form a linked list which is maintained separately from the +L<lhash(3)|lhash(3)> operations, so that the database must not be +modified directly but by using the +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_cert_store.pod b/doc/ssl/SSL_CTX_set_cert_store.pod new file mode 100644 index 000000000000..6acf0d9f9b1c --- /dev/null +++ b/doc/ssl/SSL_CTX_set_cert_store.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); + X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_store() sets/replaces the certificate verification storage +of B<ctx> to/with B<store>. If another X509_STORE object is currently +set in B<ctx>, it will be X509_STORE_free()ed. + +SSL_CTX_get_cert_store() returns a pointer to the current certificate +verification storage. + +=head1 NOTES + +In order to verify the certificates presented by the peer, trusted CA +certificates must be accessed. These CA certificates are made available +via lookup methods, handled inside the X509_STORE. From the X509_STORE +the X509_STORE_CTX used when verifying certificates is created. + +Typically the trusted certificate store is handled indirectly via using +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. +Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions +it is possible to manipulate the X509_STORE object beyond the +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +call. + +Currently no detailed documentation on how to use the X509_STORE +object is available. Not all members of the X509_STORE are used when +the verification takes place. So will e.g. the verify_callback() be +overridden with the verify_callback() set via the +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> family of functions. +This document must therefore be updated when documentation about the +X509_STORE object and its handling becomes available. + +=head1 RETURN VALUES + +SSL_CTX_set_cert_store() does not return diagnostic output. + +SSL_CTX_get_cert_store() returns the current setting. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 000000000000..c0f4f8570851 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_verify_callback() sets the verification callback function for +I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at +the time when L<SSL_new(3)|SSL_new(3)> is called. + +=head1 NOTES + +Whenever a certificate is verified during a SSL/TLS handshake, a verification +function is called. If the application does not explicitly specify a +verification callback function, the built-in verification function is used. +If a verification callback I<callback> is specified via +SSL_CTX_set_cert_verify_callback(), the supplied callback function is called +instead. By setting I<callback> to NULL, the default behaviour is restored. + +When the verification must be performed, I<callback> will be called with +the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The +argument I<arg> is specified by the application when setting I<callback>. + +I<callback> should return 1 to indicate verification success and 0 to +indicate verification failure. If SSL_VERIFY_PEER is set and I<callback> +returns 0, the handshake will fail. As the verification procedure may +allow to continue the connection in case of failure (by always returning 1) +the verification result must be set in any case using the B<error> +member of I<x509_store_ctx> so that the calling application will be informed +about the detailed result of the verification procedure! + +Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> +function set using L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>. + +=head1 WARNINGS + +Do not mix the verification callback described in this function with the +B<verify_callback> function called during the verification process. The +latter is set using the L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> +family of functions. + +Providing a complete verification procedure including certificate purpose +settings etc is a complex task. The built-in procedure is quite powerful +and in most cases it should be sufficient to modify its behaviour using +the B<verify_callback> function. + +=head1 BUGS + +=head1 RETURN VALUES + +SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=head1 HISTORY + +Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback> +was ignored, and I<callback> was called simply as + int (*callback)(X509_STORE_CTX *) +To compile software written for previous versions of OpenSSL, a dummy +argument will have to be added to I<callback>. + +=cut diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod new file mode 100644 index 000000000000..ed64f6415702 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); + int SSL_set_cipher_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx> +using the control string B<str>. The format of the string is described +in L<ciphers(1)|ciphers(1)>. The list of ciphers is inherited by all +B<ssl> objects created from B<ctx>. + +SSL_set_cipher_list() sets the list of ciphers only for B<ssl>. + +=head1 NOTES + +The control string B<str> should be universally usable and not depend +on details of the library configuration (ciphers compiled in). Thus no +syntax checking takes place. Items that are not recognized, because the +corresponding ciphers are not compiled in or because they are mistyped, +are simply ignored. Failure is only flagged if no ciphers could be collected +at all. + +It should be noted, that inclusion of a cipher to be used into the list is +a necessary condition. On the client side, the inclusion into the list is +also sufficient. On the server side, additional restrictions apply. All ciphers +have additional requirements. ADH ciphers don't need a certificate, but +DH-parameters must have been set. All other ciphers need a corresponding +certificate and key. + +A RSA cipher can only be chosen, when a RSA certificate is available. +RSA export ciphers with a keylength of 512 bits for the RSA key require +a temporary 512 bit RSA key, as typically the supplied key has a length +of 1024 bit (see +L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). +RSA ciphers using EDH need a certificate and key and additional DH-parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). + +A DSA cipher can only be chosen, when a DSA certificate is available. +DSA ciphers always use DH key exchange and therefore need DH-parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). + +When these conditions are not met for any cipher in the list (e.g. a +client only supports export RSA ciphers with a asymmetric key length +of 512 bits and the server is not configured to use temporary RSA +keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated +and the handshake will fail. + +=head1 RETURN VALUES + +SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher +could be selected and 0 on complete failure. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, +L<ciphers(1)|ciphers(1)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_client_CA_list.pod b/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 000000000000..632b556d1262 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, +SSL_add_client_CA - set list of CAs sent to the client when requesting a +client certificate + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); + void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); + int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); + int SSL_add_client_CA(SSL *ssl, X509 *cacert); + +=head1 DESCRIPTION + +SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for B<ctx>. + +SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for the chosen B<ssl>, overriding the +setting valid for B<ssl>'s SSL_CTX object. + +SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +B<ctx>. + +SSL_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. + +=head1 NOTES + +When a TLS/SSL server requests a client certificate (see +B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which +it will accept certificates, to the client. + +This list must explicitly be set using SSL_CTX_set_client_CA_list() for +B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list +specified overrides the previous setting. The CAs listed do not become +trusted (B<list> only contains the names, not the complete certificates); use +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +to additionally load them for verification. + +If the list of acceptable CAs is compiled in a file, the +L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)> +function can be used to help importing the necessary data. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional +items the list of client CAs. If no list was specified before using +SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client +CA list for B<ctx> or B<ssl> (as appropriate) is opened. + +These functions are only useful for TLS/SSL servers. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item 1 + +The operation succeeded. + +=item 0 + +A failure while manipulating the STACK_OF(X509_NAME) object occurred or +the X509_NAME could not be extracted from B<cacert>. Check the error stack +to find out the reason. + +=back + +=head1 EXAMPLES + +Scan all certificates in B<CAfile> and list them as acceptable CAs: + + SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile)); + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/doc/ssl/SSL_CTX_set_client_cert_cb.pod new file mode 100644 index 000000000000..3465b5c7bbaf --- /dev/null +++ b/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); + int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + +=head1 DESCRIPTION + +SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is +called when a client certificate is requested by a server and no certificate +was yet set for the SSL object. + +When B<client_cert_cb()> is NULL, no callback function is used. + +SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback +function. + +client_cert_cb() is the application defined callback. If it wants to +set a certificate, a certificate/private key combination must be set +using the B<x509> and B<pkey> arguments and "1" must be returned. The +certificate will be installed into B<ssl>, see the NOTES and BUGS sections. +If no certificate should be set, "0" has to be returned and no certificate +will be sent. A negative return value will suspend the handshake and the +handshake function will return immediatly. L<SSL_get_error(3)|SSL_get_error(3)> +will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was +suspended. The next call to the handshake function will again lead to the call +of client_cert_cb(). It is the job of the client_cert_cb() to store information +about the state of the last call, if required to continue. + +=head1 NOTES + +During a handshake (or renegotiation) a server may request a certificate +from the client. A client certificate must only be sent, when the server +did send the request. + +When a certificate was set using the +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions, +it will be sent to the server. The TLS standard requires that only a +certificate is sent, if it matches the list of acceptable CAs sent by the +server. This constraint is violated by the default behavior of the OpenSSL +library. Using the callback function it is possible to implement a proper +selection routine or to allow a user interaction to choose the certificate to +be sent. + +If a callback function is defined and no certificate was yet defined for the +SSL object, the callback function will be called. +If the callback function returns a certificate, the OpenSSL library +will try to load the private key and certificate data into the SSL +object using the SSL_use_certificate() and SSL_use_private_key() functions. +Thus it will permanently install the certificate and key for this SSL +object. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>. +If the callback returns no certificate, the OpenSSL library will not send +a certificate. + +=head1 BUGS + +The client_cert_cb() cannot return a complete certificate chain, it can +only return one client certificate. If the chain only has a length of 2, +the root CA certificate may be omitted according to the TLS standard and +thus a standard conforming answer can be sent to the server. For a +longer chain, the client must send the complete chain (with the option +to leave out the root CA certificate). This can only be accomplished by +either adding the intermediate CA certificates into the trusted +certificate store for the SSL_CTX object (resulting in having to add +CA certificates that otherwise maybe would not be trusted), or by adding +the chain certificates using the +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> +function, which is only available for the SSL_CTX object as a whole and that +therefore probably can only apply for one client certificate, making +the concept of the callback function (to allow the choice from several +certificates) questionable. + +Once the SSL object has been used in conjunction with the callback function, +the certificate will be set for the SSL object and will not be cleared +even when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore +mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)> +and create a new one to return to the previous state. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod new file mode 100644 index 000000000000..2b87f01ca15f --- /dev/null +++ b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); + void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); + + int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata); + +=head1 DESCRIPTION + +SSL_CTX_set_default_passwd_cb() sets the default password callback called +when loading/storing a PEM certificate with encryption. + +SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which +will be provided to the password callback on invocation. + +The pem_passwd_cb(), which must be provided by the application, hands back the +password to be used during decryption. On invocation a pointer to B<userdata> +is provided. The pem_passwd_cb must write the password into the provided buffer +B<buf> which is of size B<size>. The actual length of the password must +be returned to the calling function. B<rwflag> indicates whether the +callback is used for reading/decryption (rwflag=0) or writing/encryption +(rwflag=1). + +=head1 NOTES + +When loading or storing private keys, a password might be supplied to +protect the private key. The way this password can be supplied may depend +on the application. If only one private key is handled, it can be practical +to have pem_passwd_cb() handle the password dialog interactively. If several +keys have to be handled, it can be practical to ask for the password once, +then keep it in memory and use it several times. In the last case, the +password could be stored into the B<userdata> storage and the +pem_passwd_cb() only returns the password already stored. + +When asking for the password interactively, pem_passwd_cb() can use +B<rwflag> to check, whether an item shall be encrypted (rwflag=1). +In this case the password dialog may ask for the same password twice +for comparison in order to catch typos, that would make decryption +impossible. + +Other items in PEM formatting (certificates) can also be encrypted, it is +however not usual, as certificate information is considered public. + +=head1 RETURN VALUES + +SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata() +do not provide diagnostic information. + +=head1 EXAMPLES + +The following example returns the password provided as B<userdata> to the +calling function. The password is considered to be a '\0' terminated +string. If the password does not fit into the buffer, the password is +truncated. + + int pem_passwd_cb(char *buf, int size, int rwflag, void *password) + { + strncpy(buf, (char *)(password), size); + buf[size - 1] = '\0'; + return(strlen(buf)); + } + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_generate_session_id.pod b/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 000000000000..798e8443a711 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,150 @@ +=pod + +=head1 NAME + +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, + unsigned int *id_len); + + int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); + int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); + int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, + unsigned int id_len); + +=head1 DESCRIPTION + +SSL_CTX_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B<ctx> to be B<cb>. + +SSL_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B<ssl> to be B<cb>. + +SSL_has_matching_session_id() checks, whether a session with id B<id> +(of length B<id_len>) is already contained in the internal session cache +of the parent context of B<ssl>. + +=head1 NOTES + +When a new session is established between client and server, the server +generates a session id. The session id is an arbitrary sequence of bytes. +The length of the session id is 16 bytes for SSLv2 sessions and between +1 and 32 bytes for SSLv3/TLSv1. The session id is not security critical +but must be unique for the server. Additionally, the session id is +transmitted in the clear when reusing the session so it must not contain +sensitive information. + +Without a callback being set, an OpenSSL server will generate a unique +session id from pseudo random numbers of the maximum possible length. +Using the callback function, the session id can be changed to contain +additional information like e.g. a host id in order to improve load balancing +or external caching techniques. + +The callback function receives a pointer to the memory location to put +B<id> into and a pointer to the maximum allowed length B<id_len>. The +buffer at location B<id> is only guaranteed to have the size B<id_len>. +The callback is only allowed to generate a shorter id and reduce B<id_len>; +the callback B<must never> increase B<id_len> or write to the location +B<id> exceeding the given limit. + +If a SSLv2 session id is generated and B<id_len> is reduced, it will be +restored after the callback has finished and the session id will be padded +with 0x00. It is not recommended to change the B<id_len> for SSLv2 sessions. +The callback can use the L<SSL_get_version(3)|SSL_get_version(3)> function +to check, whether the session is of type SSLv2. + +The location B<id> is filled with 0x00 before the callback is called, so the +callback may only fill part of the possible length and leave B<id_len> +untouched while maintaining reproducibility. + +Since the sessions must be distinguished, session ids must be unique. +Without the callback a random number is used, so that the probability +of generating the same session id is extremely small (2^128 possible ids +for an SSLv2 session, 2^256 for SSLv3/TLSv1). In order to assure the +uniqueness of the generated session id, the callback must call +SSL_has_matching_session_id() and generate another id if a conflict occurs. +If an id conflict is not resolved, the handshake will fail. +If the application codes e.g. a unique host id, a unique process number, and +a unique sequence number into the session id, uniqueness could easily be +achieved without randomness added (it should however be taken care that +no confidential information is leaked this way). If the application can not +guarantee uniqueness, it is recommended to use the maximum B<id_len> and +fill in the bytes not used to code special information with random data +to avoid collisions. + +SSL_has_matching_session_id() will only query the internal session cache, +not the external one. Since the session id is generated before the +handshake is completed, it is not immediately added to the cache. If +another thread is using the same internal session cache, a race condition +can occur in that another thread generates the same session id. +Collisions can also occur when using an external session cache, since +the external cache is not tested with SSL_has_matching_session_id() +and the same race condition applies. + +When calling SSL_has_matching_session_id() for an SSLv2 session with +reduced B<id_len>, the match operation will be performed using the +fixed length required and with a 0x00 padded id. + +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. + +=head1 EXAMPLES + +The callback function listed will generate a session id with the +server id given, and will fill the rest with pseudo random bytes: + + const char session_id_prefix = "www-18"; + + #define MAX_SESSION_ID_ATTEMPTS 10 + static int generate_session_id(const SSL *ssl, unsigned char *id, + unsigned int *id_len) + { + unsigned int count = 0; + const char *version; + + version = SSL_get_version(ssl); + if (!strcmp(version, "SSLv2")) + /* we must not change id_len */; + + do { + RAND_pseudo_bytes(id, *id_len); + /* Prefix the session_id with the required prefix. NB: If our + * prefix is too long, clip it - but there will be worse effects + * anyway, eg. the server could only possibly create 1 session + * ID (ie. the prefix!) so all future session negotiations will + * fail due to conflicts. */ + memcpy(id, session_id_prefix, + (strlen(session_id_prefix) < *id_len) ? + strlen(session_id_prefix) : *id_len); + } + while(SSL_has_matching_session_id(ssl, id, *id_len) && + (++count < MAX_SESSION_ID_ATTEMPTS)); + if(count >= MAX_SESSION_ID_ATTEMPTS) + return 0; + return 1; + } + + +=head1 RETURN VALUES + +SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() +always return 1. + +SSL_has_matching_session_id() returns 1 if another session with the +same id is already in the cache. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_version(3)|SSL_get_version(3)> + +=head1 HISTORY + +SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id() +and SSL_has_matching_session_id() have been introduced in +OpenSSL 0.9.7. + +=cut diff --git a/doc/ssl/SSL_CTX_set_info_callback.pod b/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 000000000000..0b4affd5eb1a --- /dev/null +++ b/doc/ssl/SSL_CTX_set_info_callback.pod @@ -0,0 +1,153 @@ +=pod + +=head1 NAME + +SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); + void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); + + void SSL_set_info_callback(SSL *ssl, void (*callback)()); + void (*SSL_get_info_callback(const SSL *ssl))(); + +=head1 DESCRIPTION + +SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to +obtain state information for SSL objects created from B<ctx> during connection +setup and use. The setting for B<ctx> is overridden from the setting for +a specific SSL object, if specified. +When B<callback> is NULL, not callback function is used. + +SSL_set_info_callback() sets the B<callback> function, that can be used to +obtain state information for B<ssl> during connection setup and use. +When B<callback> is NULL, the callback setting currently valid for +B<ctx> is used. + +SSL_CTX_get_info_callback() returns a pointer to the currently set information +callback function for B<ctx>. + +SSL_get_info_callback() returns a pointer to the currently set information +callback function for B<ssl>. + +=head1 NOTES + +When setting up a connection and during use, it is possible to obtain state +information from the SSL/TLS engine. When set, an information callback function +is called whenever the state changes, an alert appears, or an error occurs. + +The callback function is called as B<callback(SSL *ssl, int where, int ret)>. +The B<where> argument specifies information about where (in which context) +the callback function was called. If B<ret> is 0, an error condition occurred. +If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert +information. + +B<where> is a bitmask made up of the following bits: + +=over 4 + +=item SSL_CB_LOOP + +Callback has been called to indicate state change inside a loop. + +=item SSL_CB_EXIT + +Callback has been called to indicate error exit of a handshake function. +(May be soft error with retry option for non-blocking setups.) + +=item SSL_CB_READ + +Callback has been called during read operation. + +=item SSL_CB_WRITE + +Callback has been called during write operation. + +=item SSL_CB_ALERT + +Callback has been called due to an alert being sent or received. + +=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) + +=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) + +=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) + +=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) + +=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) + +=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) + +=item SSL_CB_HANDSHAKE_START + +Callback has been called because a new handshake is started. + +=item SSL_CB_HANDSHAKE_DONE 0x20 + +Callback has been called because a handshake is finished. + +=back + +The current state information can be obtained using the +L<SSL_state_string(3)|SSL_state_string(3)> family of functions. + +The B<ret> information can be evaluated using the +L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions. + +=head1 RETURN VALUES + +SSL_set_info_callback() does not provide diagnostic information. + +SSL_get_info_callback() returns the current setting. + +=head1 EXAMPLES + +The following example callback function prints state strings, information +about alerts being handled and error messages to the B<bio_err> BIO. + + void apps_ssl_info_callback(SSL *s, int where, int ret) + { + const char *str; + int w; + + w=where& ~SSL_ST_MASK; + + if (w & SSL_ST_CONNECT) str="SSL_connect"; + else if (w & SSL_ST_ACCEPT) str="SSL_accept"; + else str="undefined"; + + if (where & SSL_CB_LOOP) + { + BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s)); + } + else if (where & SSL_CB_ALERT) + { + str=(where & SSL_CB_READ)?"read":"write"; + BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n", + str, + SSL_alert_type_string_long(ret), + SSL_alert_desc_string_long(ret)); + } + else if (where & SSL_CB_EXIT) + { + if (ret == 0) + BIO_printf(bio_err,"%s:failed in %s\n", + str,SSL_state_string_long(s)); + else if (ret < 0) + { + BIO_printf(bio_err,"%s:error in %s\n", + str,SSL_state_string_long(s)); + } + } + } + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>, +L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_max_cert_list.pod b/doc/ssl/SSL_CTX_set_max_cert_list.pod new file mode 100644 index 000000000000..da68cb9fc240 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_max_cert_list.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list, - manipulate allowed for the peer's certificate chain + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); + long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); + + long SSL_set_max_cert_list(SSL *ssl, long size); + long SSL_get_max_cert_list(SSL *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's +certificate chain for all SSL objects created from B<ctx> to be <size> bytes. +The SSL objects inherit the setting valid for B<ctx> at the time +L<SSL_new(3)|SSL_new(3)> is being called. + +SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>. + +SSL_set_max_cert_list() sets the maximum size allowed for the peer's +certificate chain for B<ssl> to be <size> bytes. This setting stays valid +until a new value is set. + +SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>. + +=head1 NOTES + +During the handshake process, the peer may send a certificate chain. +The TLS/SSL standard does not give any maximum size of the certificate chain. +The OpenSSL library handles incoming data by a dynamically allocated buffer. +In order to prevent this buffer from growing without bounds due to data +received from a faulty or malicious peer, a maximum size for the certificate +chain is set. + +The default value for the maximum certificate chain size is 100kB (30kB +on the 16bit DOS platform). This should be sufficient for usual certificate +chains (OpenSSL's default maximum chain length is 10, see +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, and certificates +without special extensions have a typical size of 1-2kB). + +For special applications it can be necessary to extend the maximum certificate +chain size allowed to be sent by the peer, see e.g. the work on +"Internet X.509 Public Key Infrastructure Proxy Certificate Profile" +and "TLS Delegation Protocol" at http://www.ietf.org/ and +http://www.globus.org/ . + +Under normal conditions it should never be necessary to set a value smaller +than the default, as the buffer is handled dynamically and only uses the +memory actually required by the data sent by the peer. + +If the maximum certificate chain size allowed is exceeded, the handshake will +fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. + +=head1 RETURN VALUES + +SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously +set value. + +SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently +set value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=head1 HISTORY + +SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7. + +=cut diff --git a/doc/ssl/SSL_CTX_set_mode.pod b/doc/ssl/SSL_CTX_set_mode.pod new file mode 100644 index 000000000000..9822544e5e2d --- /dev/null +++ b/doc/ssl/SSL_CTX_set_mode.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); + long SSL_set_mode(SSL *ssl, long mode); + + long SSL_CTX_get_mode(SSL_CTX *ctx); + long SSL_get_mode(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. +Options already set before are not cleared. + +SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. +Options already set before are not cleared. + +SSL_CTX_get_mode() returns the mode set for B<ctx>. + +SSL_get_mode() returns the mode set for B<ssl>. + +=head1 NOTES + +The following mode changes are available: + +=over 4 + +=item SSL_MODE_ENABLE_PARTIAL_WRITE + +Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success +when just a single record has been written). When not set (the default), +SSL_write() will only report success once the complete chunk was written. +Once SSL_write() returns with r, r bytes have been successfully written +and the next call to SSL_write() must only send the n-r bytes left, +imitating the behaviour of write(). + +=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER + +Make it possible to retry SSL_write() with changed buffer location +(the buffer contents must stay the same). This is not the default to avoid +the misconception that non-blocking SSL_write() behaves like +non-blocking write(). + +=item SSL_MODE_AUTO_RETRY + +Never bother the application with retries if the transport is blocking. +If a renegotiation take place during normal operation, a +L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return +with -1 and indicate the need to retry with SSL_ERROR_WANT_READ. +In a non-blocking environment applications must be prepared to handle +incomplete read/write operations. +In a blocking environment, applications are not always prepared to +deal with read/write operations returning without success report. The +flag SSL_MODE_AUTO_RETRY will cause read/write operations to only +return after the handshake and successful completion. + +=back + +=head1 RETURN VALUES + +SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask +after adding B<mode>. + +SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)> + +=head1 HISTORY + +SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6. + +=cut diff --git a/doc/ssl/SSL_CTX_set_msg_callback.pod b/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 000000000000..0015e6ea7923 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,99 @@ +=pod + +=head1 NAME + +SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg - install callback for observing protocol messages + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + + void SSL_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + +=head1 DESCRIPTION + +SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to +define a message callback function I<cb> for observing all SSL/TLS +protocol messages (such as handshake messages) that are received or +sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() +can be used to set argument I<arg> to the callback function, which is +available for arbitrary application use. + +SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify +default settings that will be copied to new B<SSL> objects by +L<SSL_new(3)|SSL_new(3)>. SSL_set_msg_callback() and +SSL_set_msg_callback_arg() modify the actual settings of an B<SSL> +object. Using a B<0> pointer for I<cb> disables the message callback. + +When I<cb> is called by the SSL/TLS library for a protocol message, +the function arguments have the following meaning: + +=over 4 + +=item I<write_p> + +This flag is B<0> when a protocol message has been received and B<1> +when a protocol message has been sent. + +=item I<version> + +The protocol version according to which the protocol message is +interpreted by the library. Currently, this is one of +B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL +3.0 and TLS 1.0, respectively). + +=item I<content_type> + +In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0 +or TLS 1.0, this is one of the B<ContentType> values defined in the +protocol specification (B<change_cipher_spec(20)>, B<alert(21)>, +B<handshake(22)>; but never B<application_data(23)> because the +callback will only be called for protocol messages). + +=item I<buf>, I<len> + +I<buf> points to a buffer containing the protocol message, which +consists of I<len> bytes. The buffer is no longer valid after the +callback function has returned. + +=item I<ssl> + +The B<SSL> object that received or sent the message. + +=item I<arg> + +The user-defined argument optionally defined by +SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). + +=back + +=head1 NOTES + +Protocol messages are passed to the callback function after decryption +and fragment collection where applicable. (Thus record boundaries are +not visible.) + +If processing a received protocol message results in an error, +the callback function may not be called. For example, the callback +function will never see messages that are considered too large to be +processed. + +Due to automatic protocol version negotiation, I<version> is not +necessarily the protocol version used by the sender of the message: If +a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, +I<version> will be B<SSL3_VERSION>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)> + +=head1 HISTORY + +SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), +SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7. + +=cut diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod new file mode 100644 index 000000000000..fa63263601c8 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_options.pod @@ -0,0 +1,235 @@ +=pod + +=head1 NAME + +SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_options(SSL_CTX *ctx, long options); + long SSL_set_options(SSL *ssl, long options); + + long SSL_CTX_get_options(SSL_CTX *ctx); + long SSL_get_options(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. +Options already set before are not cleared! + +SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. +Options already set before are not cleared! + +SSL_CTX_get_options() returns the options set for B<ctx>. + +SSL_get_options() returns the options set for B<ssl>. + +=head1 NOTES + +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bitmasks and can be combined by a logical B<or> +operation (|). Options can only be added but can never be reset. + +SSL_CTX_set_options() and SSL_set_options() affect the (external) +protocol behaviour of the SSL library. The (internal) behaviour of +the API can be changed by using the similar +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. + +During a handshake, the option settings of the SSL object are used. When +a new SSL object is created from a context using SSL_new(), the current +option setting is copied. Changes to B<ctx> do not affect already created +SSL objects. SSL_clear() does not affect the settings. + +The following B<bug workaround> options are available: + +=over 4 + +=item SSL_OP_MICROSOFT_SESS_ID_BUG + +www.microsoft.com - when talking SSLv2, if session-id reuse is +performed, the session-id passed back in the server-finished message +is different from the one decided upon. + +=item SSL_OP_NETSCAPE_CHALLENGE_BUG + +Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte +challenge but then appears to only use 16 bytes when generating the +encryption keys. Using 16 bytes is ok but it should be ok to use 32. +According to the SSLv3 spec, one should use 32 bytes for the challenge +when operating in SSLv2/v3 compatibility mode, but as mentioned above, +this breaks this server so 16 bytes is the way to go. + +=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG + +ssl3.netscape.com:443, first a connection is established with RC4-MD5. +If it is then resumed, we end up using DES-CBC3-SHA. It should be +RC4-MD5 according to 7.6.1.3, 'cipher_suite'. + +Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. +It only really shows up when connecting via SSLv2/v3 then reconnecting +via SSLv3. The cipher list changes.... + +NEW INFORMATION. Try connecting with a cipher list of just +DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses +RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when +doing a re-connect, always takes the first cipher in the cipher list. + +=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG + +... + +=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER + +... + +=item SSL_OP_MSIE_SSLV2_RSA_PADDING + +As of OpenSSL 0.9.7h and 0.9.8a, this option has no effect. + +=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG + +... + +=item SSL_OP_TLS_D5_BUG + +... + +=item SSL_OP_TLS_BLOCK_PADDING_BUG + +... + +=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS + +Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol +vulnerability affecting CBC ciphers, which cannot be handled by some +broken SSL implementations. This option has no effect for connections +using other ciphers. + +=item SSL_OP_ALL + +All of the above bug workarounds. + +=back + +It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround +options if compatibility with somewhat broken implementations is +desired. + +The following B<modifying> options are available: + +=over 4 + +=item SSL_OP_TLS_ROLLBACK_BUG + +Disable version rollback attack detection. + +During the client key exchange, the client must send the same information +about acceptable SSL/TLS protocol levels as during the first hello. Some +clients violate this rule by adapting to the server's answer. (Example: +the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server +only understands up to SSLv3. In this case the client must still use the +same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect +to the server's answer and violate the version rollback protection.) + +=item SSL_OP_SINGLE_DH_USE + +Always create a new key when using temporary/ephemeral DH parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). +This option must be used to prevent small subgroup attacks, when +the DH parameters were not generated using "strong" primes +(e.g. when using DSA-parameters, see L<dhparam(1)|dhparam(1)>). +If "strong" primes were used, it is not strictly necessary to generate +a new DH key during each handshake but it is also recommended. +B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever +temporary/ephemeral DH parameters are used. + +=item SSL_OP_EPHEMERAL_RSA + +Always use ephemeral (temporary) RSA key when doing RSA operations +(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). +According to the specifications this is only done, when a RSA key +can only be used for signature operations (namely under export ciphers +with restricted RSA keylength). By setting this option, ephemeral +RSA keys are always used. This option breaks compatibility with the +SSL/TLS specifications and may lead to interoperability problems with +clients and should therefore never be used. Ciphers with EDH (ephemeral +Diffie-Hellman) key exchange should be used instead. + +=item SSL_OP_CIPHER_SERVER_PREFERENCE + +When choosing a cipher, use the server's preferences instead of the client +preferences. When not set, the SSL server will always follow the clients +preferences. When set, the SSLv3/TLSv1 server will choose following its +own preferences. Because of the different protocol, for SSLv2 the server +will send its list of preferences to the client and the client chooses. + +=item SSL_OP_PKCS1_CHECK_1 + +... + +=item SSL_OP_PKCS1_CHECK_2 + +... + +=item SSL_OP_NETSCAPE_CA_DN_BUG + +If we accept a netscape connection, demand a client cert, have a +non-self-signed CA which does not have its CA in netscape, and the +browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta + +=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG + +... + +=item SSL_OP_NO_SSLv2 + +Do not use the SSLv2 protocol. + +=item SSL_OP_NO_SSLv3 + +Do not use the SSLv3 protocol. + +=item SSL_OP_NO_TLSv1 + +Do not use the TLSv1 protocol. + +=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION + +When performing renegotiation as a server, always start a new session +(i.e., session resumption requests are only accepted in the initial +handshake). This option is not needed for clients. + +=back + +=head1 RETURN VALUES + +SSL_CTX_set_options() and SSL_set_options() return the new options bitmask +after adding B<options>. + +SSL_CTX_get_options() and SSL_get_options() return the current bitmask. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, +L<dhparam(1)|dhparam(1)> + +=head1 HISTORY + +B<SSL_OP_CIPHER_SERVER_PREFERENCE> and +B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in +OpenSSL 0.9.7. + +B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically +enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> +and must be explicitly set. + +B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. +Versions up to OpenSSL 0.9.6c do not include the countermeasure that +can be disabled with this option (in OpenSSL 0.9.6d, it was always +enabled). + +=cut diff --git a/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/doc/ssl/SSL_CTX_set_quiet_shutdown.pod new file mode 100644 index 000000000000..393f8ff0b467 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_quiet_shutdown.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); + int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); + + void SSL_set_quiet_shutdown(SSL *ssl, int mode); + int SSL_get_quiet_shutdown(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be +B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time +L<SSL_new(3)|SSL_new(3)> is called. B<mode> may be 0 or 1. + +SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>. + +SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be +B<mode>. The setting stays valid until B<ssl> is removed with +L<SSL_free(3)|SSL_free(3)> or SSL_set_quiet_shutdown() is called again. +It is not changed when L<SSL_clear(3)|SSL_clear(3)> is called. +B<mode> may be 0 or 1. + +SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>. + +=head1 NOTES + +Normally when a SSL connection is finished, the parties must send out +"close notify" alert messages using L<SSL_shutdown(3)|SSL_shutdown(3)> +for a clean shutdown. + +When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)|SSL_shutdown(3)> +will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. +(L<SSL_shutdown(3)|SSL_shutdown(3)> then behaves like +L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> called with +SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.) +The session is thus considered to be shutdown, but no "close notify" alert +is sent to the peer. This behaviour violates the TLS standard. + +The default is normal shutdown behaviour as described by the TLS standard. + +=head1 RETURN VALUES + +SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return +diagnostic information. + +SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current +setting. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, +L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, L<SSL_new(3)|SSL_new(3)>, +L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod new file mode 100644 index 000000000000..c5d2f43dff15 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,137 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); + long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_session_cache_mode() enables/disables session caching +by setting the operational mode for B<ctx> to <mode>. + +SSL_CTX_get_session_cache_mode() returns the currently used cache mode. + +=head1 NOTES + +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each B<ctx>, if more than one +SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX +object. + +In order to reuse a session, a client must send the session's id to the +server. It can only send exactly one id. The server then either +agrees to reuse the session or it starts a full handshake (to create a new +session). + +A server will lookup up the session in its internal session storage. If the +session is not found in internal storage or lookups for the internal storage +have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try +the external storage if available. + +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). + +The following session cache modes and modifiers are available: + +=over 4 + +=item SSL_SESS_CACHE_OFF + +No session caching for client or server takes place. + +=item SSL_SESS_CACHE_CLIENT + +Client sessions are added to the session cache. As there is no reliable way +for the OpenSSL library to know whether a session should be reused or which +session to choose (due to the abstract BIO layer the SSL engine does not +have details about the connection), the application must select the session +to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> +function. This option is not activated by default. + +=item SSL_SESS_CACHE_SERVER + +Server sessions are added to the session cache. When a client proposes a +session to be reused, the server looks for the corresponding session in (first) +the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), +then (second) in the external cache if available. If the session is found, the +server will try to reuse the session. This is the default. + +=item SSL_SESS_CACHE_BOTH + +Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. + +=item SSL_SESS_CACHE_NO_AUTO_CLEAR + +Normally the session cache is checked for expired sessions every +255 connections using the +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called +explicitly by the application. + +=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP + +By setting this flag, session-resume operations in an SSL/TLS server will not +automatically look up sessions in the internal cache, even if sessions are +automatically stored there. If external session caching callbacks are in use, +this flag guarantees that all lookups are directed to the external cache. +As automatic lookup only applies for SSL/TLS servers, the flag has no effect on +clients. + +=item SSL_SESS_CACHE_NO_INTERNAL_STORE + +Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER, +sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. +Normally a new session is added to the internal cache as well as any external +session caching (callback) that is configured for the SSL_CTX. This flag will +prevent sessions being stored in the internal cache (though the application can +add them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note: +in any SSL/TLS servers where external caching is configured, any successful +session lookups in the external cache (ie. for session-resume requests) would +normally be copied into the local cache before processing continues - this flag +prevents these additions to the internal cache as well. + +=item SSL_SESS_CACHE_NO_INTERNAL + +Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and +SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. + + +=back + +The default mode is SSL_SESS_CACHE_SERVER. + +=head1 RETURN VALUES + +SSL_CTX_set_session_cache_mode() returns the previously set cache mode. + +SSL_CTX_get_session_cache_mode() returns the currently set cache mode. + + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_session_reused(3)|SSL_session_reused(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> + +=head1 HISTORY + +SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL +were introduced in OpenSSL 0.9.6h. + +=cut diff --git a/doc/ssl/SSL_CTX_set_session_id_context.pod b/doc/ssl/SSL_CTX_set_session_id_context.pod new file mode 100644 index 000000000000..58fc685506eb --- /dev/null +++ b/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -0,0 +1,83 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ctx> object. + +SSL_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ssl> object. + +=head1 NOTES + +Sessions are generated within a certain context. When exporting/importing +sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, +to re-import a session generated from another context (e.g. another +application), which might lead to malfunctions. Therefore each application +must set its own session id context B<sid_ctx> which is used to distinguish +the contexts and is stored in exported sessions. The B<sid_ctx> can be +any kind of binary data with a given length, it is therefore possible +to use e.g. the name of the application and/or the hostname and/or service +name ... + +The session id context becomes part of the session. The session id context +is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and +SSL_set_session_id_context() functions are therefore only useful on the +server side. + +OpenSSL clients will check the session id context returned by the server +when reusing a session. + +The maximum length of the B<sid_ctx> is limited to +B<SSL_MAX_SSL_SESSION_ID_LENGTH>. + +=head1 WARNINGS + +If the session id context is not set on an SSL/TLS server and client +certificates are used, stored sessions +will not be reused but a fatal error will be flagged and the handshake +will fail. + +If a server returns a different session id context to an OpenSSL client +when reusing a session, an error will be flagged and the handshake will +fail. OpenSSL servers will always return the correct session id context, +as an OpenSSL server checks the session id context itself before reusing +a session as described above. + +=head1 RETURN VALUES + +SSL_CTX_set_session_id_context() and SSL_set_session_id_context() +return the following values: + +=over 4 + +=item 0 + +The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded +the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error +is logged to the error stack. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_ssl_version.pod b/doc/ssl/SSL_CTX_set_ssl_version.pod new file mode 100644 index 000000000000..002018096551 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method +- choose a new TLS/SSL method + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_ssl_version(SSL_CTX *ctx, SSL_METHOD *method); + int SSL_set_ssl_method(SSL *s, SSL_METHOD *method); + SSL_METHOD *SSL_get_ssl_method(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects +newly created from this B<ctx>. SSL objects already created with +L<SSL_new(3)|SSL_new(3)> are not affected, except when +L<SSL_clear(3)|SSL_clear(3)> is being called. + +SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl> +object. It may be reset, when SSL_clear() is called. + +SSL_get_ssl_method() returns a function pointer to the TLS/SSL method +set in B<ssl>. + +=head1 NOTES + +The available B<method> choices are described in +L<SSL_CTX_new(3)|SSL_CTX_new(3)>. + +When L<SSL_clear(3)|SSL_clear(3)> is called and no session is connected to +an SSL object, the method of the SSL object is reset to the method currently +set in the corresponding SSL_CTX object. + +=head1 RETURN VALUES + +The following return values can occur for SSL_CTX_set_ssl_version() +and SSL_set_ssl_method(): + +=over 4 + +=item 0 + +The new choice failed, check the error stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>, +L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_timeout.pod b/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 000000000000..e3de27c47367 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); + long SSL_CTX_get_timeout(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_timeout() sets the timeout for newly created sessions for +B<ctx> to B<t>. The timeout value B<t> must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. + +=head1 NOTES + +Whenever a new session is created, it is assigned a maximum lifetime. This +lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. If the actual time is later than creation +time plus timeout, the session is not reused. + +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. Changes of the timeout value +do not affect already established sessions. + +The expiration time of a single session can be modified using the +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)> family of functions. + +Expired sessions are removed from the internal session cache, whenever +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either +directly by the application or automatically (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) + +The default value for session timeout is decided on a per protocol +basis, see L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>. +All currently supported protocols have the same default timeout value +of 300 seconds. + +=head1 RETURN VALUES + +SSL_CTX_set_timeout() returns the previously set timeout value. + +SSL_CTX_get_timeout() returns the currently set timeout value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 000000000000..29d1f8a6fbfe --- /dev/null +++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -0,0 +1,170 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, + DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); + long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); + + void SSL_set_tmp_dh_callback(SSL_CTX *ctx, + DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); + long SSL_set_tmp_dh(SSL *ssl, DH *dh) + + DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); + +=head1 DESCRIPTION + +SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be +used when a DH parameters are required to B<tmp_dh_callback>. +The callback is inherited by all B<ssl> objects created from B<ctx>. + +SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. +The key is inherited by all B<ssl> objects created from B<ctx>. + +SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. + +SSL_set_tmp_dh() sets the parameters only for B<ssl>. + +These functions apply to SSL/TLS servers only. + +=head1 NOTES + +When using a cipher with RSA authentication, an ephemeral DH key exchange +can take place. Ciphers with DSA keys always use ephemeral DH keys as well. +In these cases, the session data are negotiated using the +ephemeral/temporary DH key and the key supplied and certified +by the certificate chain is only used for signing. +Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. + +Using ephemeral DH key exchange yields forward secrecy, as the connection +can only be decrypted, when the DH key is known. By generating a temporary +DH key inside the server application that is lost when the application +is left, it becomes impossible for an attacker to decrypt past sessions, +even if he gets hold of the normal (certified) key, as this key was +only used for signing. + +In order to perform a DH key exchange the server must use a DH group +(DH parameters) and generate a DH key. The server will always generate a new +DH key during the negotiation, when the DH parameters are supplied via +callback and/or when the SSL_OP_SINGLE_DH_USE option of +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will +immediately create a DH key, when DH parameters are supplied via +SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case, +it may happen that a key is generated on initialization without later +being needed, while on the other hand the computer time during the +negotiation is being saved. + +If "strong" primes were used to generate the DH parameters, it is not strictly +necessary to generate a new key for each handshake but it does improve forward +secrecy. If it is not assured, that "strong" primes were used (see especially +the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used +in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE +has an impact on the computer time needed during negotiation, but it is not +very large, so application authors/users should consider to always enable +this option. + +As generating DH parameters is extremely time consuming, an application +should not generate the parameters on the fly but supply the parameters. +DH parameters can be reused, as the actual key is newly generated during +the negotiation. The risk in reusing DH parameters is that an attacker +may specialize on a very often used DH group. Applications should therefore +generate their own DH parameters during the installation process using the +openssl L<dhparam(1)|dhparam(1)> application. In order to reduce the computer +time needed for this generation, it is possible to use DSA parameters +instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE +is mandatory. + +Application authors may compile in DH parameters. Files dh512.pem, +dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current +version of the OpenSSL distribution contain the 'SKIP' DH parameters, +which use safe primes and were generated verifiably pseudo-randomly. +These files can be converted into C code using the B<-C> option of the +L<dhparam(1)|dhparam(1)> application. +Authors may also generate their own set of parameters using +L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were +generated. The generation of DH parameters during installation is therefore +recommended. + +An application may either directly specify the DH parameters or +can supply the DH parameters via a callback function. The callback approach +has the advantage, that the callback may supply DH parameters for different +key lengths. + +The B<tmp_dh_callback> is called with the B<keylength> needed and +the B<is_export> information. The B<is_export> flag is set, when the +ephemeral DH key exchange is performed with an export cipher. + +=head1 EXAMPLES + +Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling +partly left out.) + + ... + /* Set up ephemeral DH stuff */ + DH *dh_512 = NULL; + DH *dh_1024 = NULL; + FILE *paramfile; + + ... + /* "openssl dhparam -out dh_param_512.pem -2 512" */ + paramfile = fopen("dh_param_512.pem", "r"); + if (paramfile) { + dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); + } + /* "openssl dhparam -out dh_param_1024.pem -2 1024" */ + paramfile = fopen("dh_param_1024.pem", "r"); + if (paramfile) { + dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); + } + ... + + /* "openssl dhparam -C -2 512" etc... */ + DH *get_dh512() { ... } + DH *get_dh1024() { ... } + + DH *tmp_dh_callback(SSL *s, int is_export, int keylength) + { + DH *dh_tmp=NULL; + + switch (keylength) { + case 512: + if (!dh_512) + dh_512 = get_dh512(); + dh_tmp = dh_512; + break; + case 1024: + if (!dh_1024) + dh_1024 = get_dh1024(); + dh_tmp = dh_1024; + break; + default: + /* Generating a key on the fly is very costly, so use what is there */ + setup_dh_parameters_like_above(); + } + return(dh_tmp); + } + +=head1 RETURN VALUES + +SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return +diagnostic output. + +SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 +on failure. Check the error queue to find out the reason of failure. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, +L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod new file mode 100644 index 000000000000..534643cd9de4 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, + RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); + long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa); + long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx); + + void SSL_set_tmp_rsa_callback(SSL_CTX *ctx, + RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); + long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa) + long SSL_need_tmp_rsa(SSL *ssl) + + RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength); + +=head1 DESCRIPTION + +SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be +used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>. +The callback is inherited by all SSL objects newly created from B<ctx> +with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. + +SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be +B<rsa>. The key is inherited by all SSL objects newly created from B<ctx> +with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. + +SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed +for RSA-based strength-limited 'exportable' ciphersuites because a RSA key +with a keysize larger than 512 bits is installed. + +SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>. + +SSL_set_tmp_rsa() sets the key only for B<ssl>. + +SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed, +for RSA-based strength-limited 'exportable' ciphersuites because a RSA key +with a keysize larger than 512 bits is installed. + +These functions apply to SSL/TLS servers only. + +=head1 NOTES + +When using a cipher with RSA authentication, an ephemeral RSA key exchange +can take place. In this case the session data are negotiated using the +ephemeral/temporary RSA key and the RSA key supplied and certified +by the certificate chain is only used for signing. + +Under previous export restrictions, ciphers with RSA keys shorter (512 bits) +than the usual key length of 1024 bits were created. To use these ciphers +with RSA keys of usual length, an ephemeral key exchange must be performed, +as the normal (certified) key cannot be directly used. + +Using ephemeral RSA key exchange yields forward secrecy, as the connection +can only be decrypted, when the RSA key is known. By generating a temporary +RSA key inside the server application that is lost when the application +is left, it becomes impossible for an attacker to decrypt past sessions, +even if he gets hold of the normal (certified) RSA key, as this key was +used for signing only. The downside is that creating a RSA key is +computationally expensive. + +Additionally, the use of ephemeral RSA key exchange is only allowed in +the TLS standard, when the RSA key can be used for signing only, that is +for export ciphers. Using ephemeral RSA key exchange for other purposes +violates the standard and can break interoperability with clients. +It is therefore strongly recommended to not use ephemeral RSA key +exchange and use EDH (Ephemeral Diffie-Hellman) key exchange instead +in order to achieve forward secrecy (see +L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). + +On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default +and must be explicitly enabled using the SSL_OP_EPHEMERAL_RSA option of +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, violating the TLS/SSL +standard. When ephemeral RSA key exchange is required for export ciphers, +it will automatically be used without this option! + +An application may either directly specify the key or can supply the key via +a callback function. The callback approach has the advantage, that the +callback may generate the key only in case it is actually needed. As the +generation of a RSA key is however costly, it will lead to a significant +delay in the handshake procedure. Another advantage of the callback function +is that it can supply keys of different size (e.g. for SSL_OP_EPHEMERAL_RSA +usage) while the explicit setting of the key is only useful for key size of +512 bits to satisfy the export restricted ciphers and does give away key length +if a longer key would be allowed. + +The B<tmp_rsa_callback> is called with the B<keylength> needed and +the B<is_export> information. The B<is_export> flag is set, when the +ephemeral RSA key exchange is performed with an export cipher. + +=head1 EXAMPLES + +Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the +generation of a RSA key costs a lot of computer time, they saved for later +reuse. For demonstration purposes, two keys for 512 bits and 1024 bits +respectively are generated. + + ... + /* Set up ephemeral RSA stuff */ + RSA *rsa_512 = NULL; + RSA *rsa_1024 = NULL; + + rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL); + if (rsa_512 == NULL) + evaluate_error_queue(); + + rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL); + if (rsa_1024 == NULL) + evaluate_error_queue(); + + ... + + RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength) + { + RSA *rsa_tmp=NULL; + + switch (keylength) { + case 512: + if (rsa_512) + rsa_tmp = rsa_512; + else { /* generate on the fly, should not happen in this example */ + rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL); + rsa_512 = rsa_tmp; /* Remember for later reuse */ + } + break; + case 1024: + if (rsa_1024) + rsa_tmp=rsa_1024; + else + should_not_happen_in_this_example(); + break; + default: + /* Generating a key on the fly is very costly, so use what is there */ + if (rsa_1024) + rsa_tmp=rsa_1024; + else + rsa_tmp=rsa_512; /* Use at least a shorter key */ + } + return(rsa_tmp); + } + +=head1 RETURN VALUES + +SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return +diagnostic output. + +SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0 +on failure. Check the error queue to find out the reason of failure. + +SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary +RSA key is needed and 0 otherwise. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_new(3)|SSL_new(3)>, L<ciphers(1)|ciphers(1)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod new file mode 100644 index 000000000000..ca8d81b82c81 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_verify.pod @@ -0,0 +1,294 @@ +=pod + +=head1 NAME + +SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, + int (*verify_callback)(int, X509_STORE_CTX *)); + void SSL_set_verify(SSL *s, int mode, + int (*verify_callback)(int, X509_STORE_CTX *)); + void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); + void SSL_set_verify_depth(SSL *s, int depth); + + int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. + +SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. In +this case last B<verify_callback> set specifically for this B<ssl> remains. If +no special B<callback> was set before, the default callback for the underlying +B<ctx> is used, that was valid at the the time B<ssl> was created with +L<SSL_new(3)|SSL_new(3)>. + +SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ctx>. (See the BUGS section.) + +SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ssl>. (See the BUGS section.) + +=head1 NOTES + +The verification of certificates can be controlled by a set of logically +or'ed B<mode> flags: + +=over 4 + +=item SSL_VERIFY_NONE + +B<Server mode:> the server will not send a client certificate request to the +client, so the client will not send a certificate. + +B<Client mode:> if not using an anonymous cipher (by default disabled), the +server will send a certificate which will be checked. The result of the +certificate verification process can be checked after the TLS/SSL handshake +using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function. +The handshake will be continued regardless of the verification result. + +=item SSL_VERIFY_PEER + +B<Server mode:> the server sends a client certificate request to the client. +The certificate returned (if any) is checked. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. +The behaviour can be controlled by the additional +SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. + +B<Client mode:> the server certificate is verified. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. If no server certificate is sent, because an +anonymous cipher is used, SSL_VERIFY_PEER is ignored. + +=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT + +B<Server mode:> if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a "handshake failure" alert. +This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=item SSL_VERIFY_CLIENT_ONCE + +B<Server mode:> only request a client certificate on the initial TLS/SSL +handshake. Do not ask for a client certificate again in case of a +renegotiation. This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=back + +Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be +set at any time. + +The actual verification procedure is performed either using the built-in +verification procedure or using another application provided verification +function set with +L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. +The following descriptions apply in the case of the built-in procedure. An +application provided procedure also has access to the verify depth information +and the verify_callback() function, but the way this information is used +may be different. + +SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up +to which depth certificates in a chain are used during the verification +procedure. If the certificate chain is longer than allowed, the certificates +above the limit are ignored. Error messages are generated as if these +certificates would not be present, most likely a +X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. +The depth count is "level 0:peer certificate", "level 1: CA certificate", +"level 2: higher level CA certificate", and so on. Setting the maximum +depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9, +allowing for the peer certificate and additional 9 CA certificates. + +The B<verify_callback> function is used to control the behaviour when the +SSL_VERIFY_PEER flag is set. It must be supplied by the application and +receives two arguments: B<preverify_ok> indicates, whether the verification of +the certificate in question was passed (preverify_ok=1) or not +(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used +for the certificate chain verification. + +The certificate chain is checked starting with the deepest nesting level +(the root CA certificate) and worked upward to the peer's certificate. +At each level signatures and issuer attributes are checked. Whenever +a verification error is found, the error number is stored in B<x509_ctx> +and B<verify_callback> is called with B<preverify_ok>=0. By applying +X509_CTX_store_* functions B<verify_callback> can locate the certificate +in question and perform additional steps (see EXAMPLES). If no error is +found for a certificate, B<verify_callback> is called with B<preverify_ok>=1 +before advancing to the next level. + +The return value of B<verify_callback> controls the strategy of the further +verification process. If B<verify_callback> returns 0, the verification +process is immediately stopped with "verification failed" state. If +SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and +the TLS/SSL handshake is terminated. If B<verify_callback> returns 1, +the verification process is continued. If B<verify_callback> always returns +1, the TLS/SSL handshake will not be terminated with respect to verification +failures and the connection will be established. The calling process can +however retrieve the error code of the last verification error using +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its +own error storage managed by B<verify_callback>. + +If no B<verify_callback> is specified, the default callback will be used. +Its return value is identical to B<preverify_ok>, so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if SSL_VERIFY_PEER is set. + +=head1 BUGS + +In client mode, it is not checked whether the SSL_VERIFY_PEER flag +is set, but whether SSL_VERIFY_NONE is not set. This can lead to +unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not +used as required (exactly one must be set at any time). + +The certificate verification depth set with SSL[_CTX]_verify_depth() +stops the verification at a certain depth. The error message produced +will be that of an incomplete certificate chain and not +X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. + +=head1 RETURN VALUES + +The SSL*_set_verify*() functions do not provide diagnostic information. + +=head1 EXAMPLES + +The following code sequence realizes an example B<verify_callback> function +that will always continue the TLS/SSL handshake regardless of verification +failure, if wished. The callback realizes a verification depth limit with +more informational output. + +All verification errors are printed, informations about the certificate chain +are printed on request. +The example is realized for a server that does allow but not require client +certificates. + +The example makes use of the ex_data technique to store application data +into/retrieve application data from the SSL structure +(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). + + ... + typedef struct { + int verbose_mode; + int verify_depth; + int always_continue; + } mydata_t; + int mydata_index; + ... + static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) + { + char buf[256]; + X509 *err_cert; + int err, depth; + SSL *ssl; + mydata_t *mydata; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + /* + * Retrieve the pointer to the SSL of the connection currently treated + * and the application specific data stored into the SSL object. + */ + ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); + mydata = SSL_get_ex_data(ssl, mydata_index); + + X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); + + /* + * Catch a too long certificate chain. The depth limit set using + * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so + * that whenever the "depth>verify_depth" condition is met, we + * have violated the limit and want to log this error condition. + * We must do it here, because the CHAIN_TOO_LONG error would not + * be found explicitly; only errors introduced by cutting off the + * additional certificates would be logged. + */ + if (depth > mydata->verify_depth) { + preverify_ok = 0; + err = X509_V_ERR_CERT_CHAIN_TOO_LONG; + X509_STORE_CTX_set_error(ctx, err); + } + if (!preverify_ok) { + printf("verify error:num=%d:%s:depth=%d:%s\n", err, + X509_verify_cert_error_string(err), depth, buf); + } + else if (mydata->verbose_mode) + { + printf("depth=%d:%s\n", depth, buf); + } + + /* + * At this point, err contains the last verification error. We can use + * it for something special + */ + if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) + { + X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); + printf("issuer= %s\n", buf); + } + + if (mydata->always_continue) + return 1; + else + return preverify_ok; + } + ... + + mydata_t mydata; + + ... + mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); + + ... + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, + verify_callback); + + /* + * Let the verify_callback catch the verify_depth error so that we get + * an appropriate error in the logfile. + */ + SSL_CTX_set_verify_depth(verify_depth + 1); + + /* + * Set up the SSL specific data into "mydata" and store it into th SSL + * structure. + */ + mydata.verify_depth = verify_depth; ... + SSL_set_ex_data(ssl, mydata_index, &mydata); + + ... + SSL_accept(ssl); /* check of success left out for clarity */ + if (peer = SSL_get_peer_certificate(ssl)) + { + if (SSL_get_verify_result(ssl) == X509_V_OK) + { + /* The client sent a certificate which verified OK */ + } + } + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, +L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_use_certificate.pod b/doc/ssl/SSL_CTX_use_certificate.pod new file mode 100644 index 000000000000..10be95fdb109 --- /dev/null +++ b/doc/ssl/SSL_CTX_use_certificate.pod @@ -0,0 +1,169 @@ +=pod + +=head1 NAME + +SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); + int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); + int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_certificate(SSL *ssl, X509 *x); + int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); + int SSL_use_certificate_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); + + int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); + int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, + long len); + int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); + int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); + int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); + int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len); + int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); + int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); + int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); + int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_check_private_key(const SSL_CTX *ctx); + int SSL_check_private_key(const SSL *ssl); + +=head1 DESCRIPTION + +These functions load the certificates and private keys into the SSL_CTX +or SSL object, respectively. + +The SSL_CTX_* class of functions loads the certificates and keys into the +SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> +created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that +changes applied to B<ctx> do not propagate to already existing SSL objects. + +The SSL_* class of functions only loads certificates and keys into a +specific SSL object. The specific information is kept, when +L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object. + +SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>, +SSL_use_certificate() loads B<x> into B<ssl>. The rest of the +certificates needed to form the complete certificate chain can be +specified using the +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> +function. + +SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from +the memory location B<d> (with length B<len>) into B<ctx>, +SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. + +SSL_CTX_use_certificate_file() loads the first certificate stored in B<file> +into B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. +See the NOTES section on why SSL_CTX_use_certificate_chain_file() +should be preferred. + +SSL_CTX_use_certificate_chain_file() loads a certificate chain from +B<file> into B<ctx>. The certificates must be in PEM format and must +be sorted starting with the subject's certificate (actual client or server +certificate), followed by intermediate CA certificates if applicable, and +ending at the highest level (root) CA. +There is no corresponding function working on a single SSL object. + +SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. +SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA +to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; +SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. +If a certificate has already been set and the private does not belong +to the certificate an error is returned. To change a certificate, private +key pair the new certificate needs to be set with SSL_use_certificate() +or SSL_CTX_use_certificate() before setting the private key with +SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey(). + + +SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk> +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private +key to B<ssl>. + +SSL_CTX_use_PrivateKey_file() adds the first private key found in +B<file> to B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in +B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found +in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private +RSA key found to B<ssl>. + +SSL_CTX_check_private_key() checks the consistency of a private key with +the corresponding certificate loaded into B<ctx>. If more than one +key/certificate pair (RSA/DSA) is installed, the last item installed will +be checked. If e.g. the last item was a RSA certificate or key, the RSA +key/certificate pair will be checked. SSL_check_private_key() performs +the same check for B<ssl>. If no key/certificate was explicitly added for +this B<ssl>, the last item added into B<ctx> will be checked. + +=head1 NOTES + +The internal certificate store of OpenSSL can hold two private key/certificate +pairs at a time: one key/certificate of type RSA and one key/certificate +of type DSA. The certificate used depends on the cipher select, see +also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>. + +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain +one certificate or private key, consequently +SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. +Files of type SSL_FILETYPE_PEM can contain more than one item. + +SSL_CTX_use_certificate_chain_file() adds the first certificate found +in the file to the certificate store. The other certificates are added +to the store of chain certificates using +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>. +There exists only one extra chain store, so that the same chain is appended +to both types of certificates, RSA and DSA! If it is not intended to use +both type of certificate at the same time, it is recommended to use the +SSL_CTX_use_certificate_chain_file() instead of the +SSL_CTX_use_certificate_file() function in order to allow the use of +complete certificate chains even when no trusted CA storage is used or +when the CA issuing the certificate shall not be added to the trusted +CA storage. + +If additional certificates are needed to complete the chain during the +TLS negotiation, CA certificates are additionally looked up in the +locations of trusted CA certificates, see +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. + +The private keys loaded from file can be encrypted. In order to successfully +load encrypted keys, a function returning the passphrase must have been +supplied, see +L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>. +(Certificate files might be encrypted as well from the technical point +of view, it however does not make sense as the data in the certificate +is considered public anyway.) + +=head1 RETURN VALUES + +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, +L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> + +=head1 HISTORY + +Support for DER encoded private keys (SSL_FILETYPE_ASN1) in +SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added +in 0.9.8 . + +=cut diff --git a/doc/ssl/SSL_SESSION_free.pod b/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 000000000000..558de01df91d --- /dev/null +++ b/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_SESSION_free - free an allocated SSL_SESSION structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_free() decrements the reference count of B<session> and removes +the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated +memory, if the the reference count has reached 0. + +=head1 NOTES + +SSL_SESSION objects are allocated, when a TLS/SSL handshake operation +is successfully completed. Depending on the settings, see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +the SSL_SESSION objects are internally referenced by the SSL_CTX and +linked into its session cache. SSL objects may be using the SSL_SESSION object; +as a session may be reused, several SSL objects may be using one SSL_SESSION +object at the same time. It is therefore crucial to keep the reference +count (usage information) correct and not delete a SSL_SESSION object +that is still used, as this may lead to program failures due to +dangling pointers. These failures may also appear delayed, e.g. +when an SSL_SESSION object was completely freed as the reference count +incorrectly became 0, but it is still referenced in the internal +session cache and the cache list is processed during a +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> operation. + +SSL_SESSION_free() must only be called for SSL_SESSION objects, for +which the reference count was explicitly incremented (e.g. +by calling SSL_get1_session(), see L<SSL_get_session(3)|SSL_get_session(3)>) +or when the SSL_SESSION object was generated outside a TLS handshake +operation, e.g. by using L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>. +It must not be called on other SSL_SESSION objects, as this would cause +incorrect reference counts and therefore program failures. + +=head1 RETURN VALUES + +SSL_SESSION_free() does not provide diagnostic information. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, + L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> + +=cut diff --git a/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/doc/ssl/SSL_SESSION_get_ex_new_index.pod new file mode 100644 index 000000000000..657cda931ff9 --- /dev/null +++ b/doc/ssl/SSL_SESSION_get_ex_new_index.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); + + void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_SESSION_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx> +into the B<session> object. + +SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from +B<session>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 WARNINGS + +The application data is only maintained for sessions held in memory. The +application data is not included when dumping the session with +i2d_SSL_SESSION() (and all functions indirectly calling the dump functions +like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can +therefore not be restored. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/doc/ssl/SSL_SESSION_get_time.pod b/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 000000000000..490337a32f0f --- /dev/null +++ b/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_set_timeout - retrieve and manipulate session time and timeout settings + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_SESSION_get_time(const SSL_SESSION *s); + long SSL_SESSION_set_time(SSL_SESSION *s, long tm); + long SSL_SESSION_get_timeout(const SSL_SESSION *s); + long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); + + long SSL_get_time(const SSL_SESSION *s); + long SSL_set_time(SSL_SESSION *s, long tm); + long SSL_get_timeout(const SSL_SESSION *s); + long SSL_set_timeout(SSL_SESSION *s, long tm); + +=head1 DESCRIPTION + +SSL_SESSION_get_time() returns the time at which the session B<s> was +established. The time is given in seconds since the Epoch and therefore +compatible to the time delivered by the time() call. + +SSL_SESSION_set_time() replaces the creation time of the session B<s> with +the chosen value B<tm>. + +SSL_SESSION_get_timeout() returns the timeout value set for session B<s> +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds +to B<tm>. + +The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() +functions are synonyms for the SSL_SESSION_*() counterparts. + +=head1 NOTES + +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the +default timeout value at creation, respectively, as set by +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>. +Using these functions it is possible to extend or shorten the lifetime +of the session. + +=head1 RETURN VALUES + +SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently +valid values. + +SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. + +If any of the function is passed the NULL pointer for the session B<s>, +0 is returned. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> + +=cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod new file mode 100644 index 000000000000..cc724c0d561a --- /dev/null +++ b/doc/ssl/SSL_accept.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_accept(SSL *ssl); + +=head1 DESCRIPTION + +SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake. +The communication channel must already have been set and assigned to the +B<ssl> by setting an underlying B<BIO>. + +=head1 NOTES + +The behaviour of SSL_accept() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_accept() will only return once the +handshake has been finished or an error occurred, except for SGC (Server +Gated Cryptography). For SGC, SSL_accept() may return with -1, but +SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and SSL_accept() +should be called again. + +If the underlying BIO is B<non-blocking>, SSL_accept() will also return +when the underlying BIO could not satisfy the needs of SSL_accept() +to continue the handshake, indicating the problem by the return value -1. +In this case a call to SSL_get_error() with the +return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_accept(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + +=item 0 + +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item E<lt>0 + +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, +L<SSL_CTX_new(3)|SSL_CTX_new(3)> + +=cut diff --git a/doc/ssl/SSL_alert_type_string.pod b/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 000000000000..94e28cc3075e --- /dev/null +++ b/doc/ssl/SSL_alert_type_string.pod @@ -0,0 +1,228 @@ +=pod + +=head1 NAME + +SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_alert_type_string(int value); + const char *SSL_alert_type_string_long(int value); + + const char *SSL_alert_desc_string(int value); + const char *SSL_alert_desc_string_long(int value); + +=head1 DESCRIPTION + +SSL_alert_type_string() returns a one letter string indicating the +type of the alert specified by B<value>. + +SSL_alert_type_string_long() returns a string indicating the type of the alert +specified by B<value>. + +SSL_alert_desc_string() returns a two letter string as a short form +describing the reason of the alert specified by B<value>. + +SSL_alert_desc_string_long() returns a string describing the reason +of the alert specified by B<value>. + +=head1 NOTES + +When one side of an SSL/TLS communication wants to inform the peer about +a special situation, it sends an alert. The alert is sent as a special message +and does not influence the normal data stream (unless its contents results +in the communication being canceled). + +A warning alert is sent, when a non-fatal error condition occurs. The +"close notify" alert is sent as a warning alert. Other examples for +non-fatal errors are certificate errors ("certificate expired", +"unsupported certificate"), for which a warning alert may be sent. +(The sending party may however decide to send a fatal error.) The +receiving side may cancel the connection on reception of a warning +alert on it discretion. + +Several alert messages must be sent as fatal alert messages as specified +by the TLS RFC. A fatal alert always leads to a connection abort. + +=head1 RETURN VALUES + +The following strings can occur for SSL_alert_type_string() or +SSL_alert_type_string_long(): + +=over 4 + +=item "W"/"warning" + +=item "F"/"fatal" + +=item "U"/"unknown" + +This indicates that no support is available for this alert type. +Probably B<value> does not contain a correct alert message. + +=back + +The following strings can occur for SSL_alert_desc_string() or +SSL_alert_desc_string_long(): + +=over 4 + +=item "CN"/"close notify" + +The connection shall be closed. This is a warning alert. + +=item "UM"/"unexpected message" + +An inappropriate message was received. This alert is always fatal +and should never be observed in communication between proper +implementations. + +=item "BM"/"bad record mac" + +This alert is returned if a record is received with an incorrect +MAC. This message is always fatal. + +=item "DF"/"decompression failure" + +The decompression function received improper input (e.g. data +that would expand to excessive length). This message is always +fatal. + +=item "HF"/"handshake failure" + +Reception of a handshake_failure alert message indicates that the +sender was unable to negotiate an acceptable set of security +parameters given the options available. This is a fatal error. + +=item "NC"/"no certificate" + +A client, that was asked to send a certificate, does not send a certificate +(SSLv3 only). + +=item "BC"/"bad certificate" + +A certificate was corrupt, contained signatures that did not +verify correctly, etc + +=item "UC"/"unsupported certificate" + +A certificate was of an unsupported type. + +=item "CR"/"certificate revoked" + +A certificate was revoked by its signer. + +=item "CE"/"certificate expired" + +A certificate has expired or is not currently valid. + +=item "CU"/"certificate unknown" + +Some other (unspecified) issue arose in processing the +certificate, rendering it unacceptable. + +=item "IP"/"illegal parameter" + +A field in the handshake was out of range or inconsistent with +other fields. This is always fatal. + +=item "DC"/"decryption failed" + +A TLSCiphertext decrypted in an invalid way: either it wasn't an +even multiple of the block length or its padding values, when +checked, weren't correct. This message is always fatal. + +=item "RO"/"record overflow" + +A TLSCiphertext record was received which had a length more than +2^14+2048 bytes, or a record decrypted to a TLSCompressed record +with more than 2^14+1024 bytes. This message is always fatal. + +=item "CA"/"unknown CA" + +A valid certificate chain or partial chain was received, but the +certificate was not accepted because the CA certificate could not +be located or couldn't be matched with a known, trusted CA. This +message is always fatal. + +=item "AD"/"access denied" + +A valid certificate was received, but when access control was +applied, the sender decided not to proceed with negotiation. +This message is always fatal. + +=item "DE"/"decode error" + +A message could not be decoded because some field was out of the +specified range or the length of the message was incorrect. This +message is always fatal. + +=item "CY"/"decrypt error" + +A handshake cryptographic operation failed, including being +unable to correctly verify a signature, decrypt a key exchange, +or validate a finished message. + +=item "ER"/"export restriction" + +A negotiation not in compliance with export restrictions was +detected; for example, attempting to transfer a 1024 bit +ephemeral RSA key for the RSA_EXPORT handshake method. This +message is always fatal. + +=item "PV"/"protocol version" + +The protocol version the client has attempted to negotiate is +recognized, but not supported. (For example, old protocol +versions might be avoided for security reasons). This message is +always fatal. + +=item "IS"/"insufficient security" + +Returned instead of handshake_failure when a negotiation has +failed specifically because the server requires ciphers more +secure than those supported by the client. This message is always +fatal. + +=item "IE"/"internal error" + +An internal error unrelated to the peer or the correctness of the +protocol makes it impossible to continue (such as a memory +allocation failure). This message is always fatal. + +=item "US"/"user canceled" + +This handshake is being canceled for some reason unrelated to a +protocol failure. If the user cancels an operation after the +handshake is complete, just closing the connection by sending a +close_notify is more appropriate. This alert should be followed +by a close_notify. This message is generally a warning. + +=item "NR"/"no renegotiation" + +Sent by the client in response to a hello request or by the +server in response to a client hello after initial handshaking. +Either of these would normally lead to renegotiation; when that +is not appropriate, the recipient should respond with this alert; +at that point, the original requester can decide whether to +proceed with the connection. One case where this would be +appropriate would be where a server has spawned a process to +satisfy a request; the process might receive security parameters +(key length, authentication, etc.) at startup and it might be +difficult to communicate changes to these parameters after that +point. This message is always a warning. + +=item "UK"/"unknown" + +This indicates that no description is available for this alert type. +Probably B<value> does not contain a correct alert message. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> + +=cut diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod new file mode 100644 index 000000000000..8e077e31c9a8 --- /dev/null +++ b/doc/ssl/SSL_clear.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +SSL_clear - reset SSL object to allow another connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_clear(SSL *ssl); + +=head1 DESCRIPTION + +Reset B<ssl> to allow another connection. All settings (method, ciphers, +BIOs) are kept. + +=head1 NOTES + +SSL_clear is used to prepare an SSL object for a new connection. While all +settings are kept, a side effect is the handling of the current SSL session. +If a session is still B<open>, it is considered bad and will be removed +from the session cache, as required by RFC2246. A session is considered open, +if L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection +or at least L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was used to +set the SSL_SENT_SHUTDOWN state. + +If a session was closed cleanly, the session object will be kept and all +settings corresponding. This explicitly means, that e.g. the special method +used during the session will be kept for the next handshake. So if the +session was a TLSv1 session, a SSL client object will use a TLSv1 client +method for the next handshake and a SSL server object will use a TLSv1 +server method, even if SSLv23_*_methods were chosen on startup. This +will might lead to connection failures (see L<SSL_new(3)|SSL_new(3)>) +for a description of the method's properties. + +=head1 WARNINGS + +SSL_clear() resets the SSL object to allow for another connection. The +reset operation however keeps several settings of the last sessions +(some of these settings were made automatically during the last +handshake). It only makes sense when opening a new session (or reusing +an old one) with the same peer that shares these settings. +SSL_clear() is not a short form for the sequence +L<SSL_free(3)|SSL_free(3)>; L<SSL_new(3)|SSL_new(3)>; . + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The SSL_clear() operation could not be performed. Check the error stack to +find out the reason. + +=item 1 + +The SSL_clear() operation was successful. + +=back + +L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)> + +=cut diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod new file mode 100644 index 000000000000..cc56ebb75f3f --- /dev/null +++ b/doc/ssl/SSL_connect.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_connect(SSL *ssl); + +=head1 DESCRIPTION + +SSL_connect() initiates the TLS/SSL handshake with a server. The communication +channel must already have been set and assigned to the B<ssl> by setting an +underlying B<BIO>. + +=head1 NOTES + +The behaviour of SSL_connect() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_connect() will only return once the +handshake has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_connect() will also return +when the underlying BIO could not satisfy the needs of SSL_connect() +to continue the handshake, indicating the problem by the return value -1. +In this case a call to SSL_get_error() with the +return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_connect(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + +=item 0 + +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item E<lt>0 + +The TLS/SSL handshake was not successful, because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, +L<SSL_CTX_new(3)|SSL_CTX_new(3)> + +=cut diff --git a/doc/ssl/SSL_do_handshake.pod b/doc/ssl/SSL_do_handshake.pod new file mode 100644 index 000000000000..243576451b7f --- /dev/null +++ b/doc/ssl/SSL_do_handshake.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +SSL_do_handshake - perform a TLS/SSL handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_do_handshake(SSL *ssl); + +=head1 DESCRIPTION + +SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the +connection is in client mode, the handshake will be started. The handshake +routines may have to be explicitly set in advance using either +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or +L<SSL_set_accept_state(3)|SSL_set_accept_state(3)>. + +=head1 NOTES + +The behaviour of SSL_do_handshake() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_do_handshake() will only return +once the handshake has been finished or an error occurred, except for SGC +(Server Gated Cryptography). For SGC, SSL_do_handshake() may return with -1, +but SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and +SSL_do_handshake() should be called again. + +If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return +when the underlying BIO could not satisfy the needs of SSL_do_handshake() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_do_handshake(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + +=item 0 + +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item E<lt>0 + +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> + +=cut diff --git a/doc/ssl/SSL_free.pod b/doc/ssl/SSL_free.pod new file mode 100644 index 000000000000..2d4f8b6168b3 --- /dev/null +++ b/doc/ssl/SSL_free.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_free - free an allocated SSL structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_free(SSL *ssl); + +=head1 DESCRIPTION + +SSL_free() decrements the reference count of B<ssl>, and removes the SSL +structure pointed to by B<ssl> and frees up the allocated memory if the +the reference count has reached 0. + +=head1 NOTES + +SSL_free() also calls the free()ing procedures for indirectly affected items, if +applicable: the buffering BIO, the read and write BIOs, +cipher lists specially created for this B<ssl>, the B<SSL_SESSION>. +Do not explicitly free these indirectly freed up items before or after +calling SSL_free(), as trying to free things twice may lead to program +failure. + +The ssl session has reference counts from two users: the SSL object, for +which the reference count is removed by SSL_free() and the internal +session cache. If the session is considered bad, because +L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection +and L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was not used to set the +SSL_SENT_SHUTDOWN state, the session will also be removed +from the session cache as required by RFC2246. + +=head1 RETURN VALUES + +SSL_free() does not provide diagnostic information. + +L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_get_SSL_CTX.pod b/doc/ssl/SSL_get_SSL_CTX.pod new file mode 100644 index 000000000000..659c482c792a --- /dev/null +++ b/doc/ssl/SSL_get_SSL_CTX.pod @@ -0,0 +1,26 @@ +=pod + +=head1 NAME + +SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which +B<ssl> was created with L<SSL_new(3)|SSL_new(3)>. + +=head1 RETURN VALUES + +The pointer to the SSL_CTX object is returned. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)> + +=cut diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod new file mode 100644 index 000000000000..aecadd9138f0 --- /dev/null +++ b/doc/ssl/SSL_get_ciphers.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); + const char *SSL_get_cipher_list(const SSL *ssl, int priority); + +=head1 DESCRIPTION + +SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>, +sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL +is returned. + +SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER +listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are +available, or there are less ciphers than B<priority> available, NULL +is returned. + +=head1 NOTES + +The details of the ciphers obtained by SSL_get_ciphers() can be obtained using +the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions. + +Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the +sorted list of available ciphers, until NULL is returned. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> + +=cut diff --git a/doc/ssl/SSL_get_client_CA_list.pod b/doc/ssl/SSL_get_client_CA_list.pod new file mode 100644 index 000000000000..68181b2407b9 --- /dev/null +++ b/doc/ssl/SSL_get_client_CA_list.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); + STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for +B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>. + +SSL_get_client_CA_list() returns the list of client CAs explicitly +set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, when in +server mode. In client mode, SSL_get_client_CA_list returns the list of +client CAs sent from the server, if any. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item STACK_OF(X509_NAMES) + +List of CA names explicitly set (for B<ctx> or in server mode) or send +by the server (client mode). + +=item NULL + +No client CA list was explicitly set (for B<ctx> or in server mode) or +the server did not send a list of CAs (client mode). + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)> + +=cut diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod new file mode 100644 index 000000000000..e5ab12491e63 --- /dev/null +++ b/doc/ssl/SSL_get_current_cipher.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, +SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); + #define SSL_get_cipher(s) \ + SSL_CIPHER_get_name(SSL_get_current_cipher(s)) + #define SSL_get_cipher_name(s) \ + SSL_CIPHER_get_name(SSL_get_current_cipher(s)) + #define SSL_get_cipher_bits(s,np) \ + SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) + #define SSL_get_cipher_version(s) \ + SSL_CIPHER_get_version(SSL_get_current_cipher(s)) + +=head1 DESCRIPTION + +SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing +the description of the actually used cipher of a connection established with +the B<ssl> object. + +SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the +name of the currently used cipher. SSL_get_cipher_bits() is a +macro to obtain the number of secret/algorithm bits used and +SSL_get_cipher_version() returns the protocol name. +See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details. + +=head1 RETURN VALUES + +SSL_get_current_cipher() returns the cipher actually used or NULL, when +no session has been established. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> + +=cut diff --git a/doc/ssl/SSL_get_default_timeout.pod b/doc/ssl/SSL_get_default_timeout.pod new file mode 100644 index 000000000000..a648a9b82df6 --- /dev/null +++ b/doc/ssl/SSL_get_default_timeout.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +SSL_get_default_timeout - get default session timeout value + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_default_timeout(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_default_timeout() returns the default timeout value assigned to +SSL_SESSION objects negotiated for the protocol valid for B<ssl>. + +=head1 NOTES + +Whenever a new session is negotiated, it is assigned a timeout value, +after which it will not be accepted for session reuse. If the timeout +value was not explicitly set using +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, the hardcoded default +timeout for the protocol will be used. + +SSL_get_default_timeout() return this hardcoded value, which is 300 seconds +for all currently supported protocols (SSLv2, SSLv3, and TLSv1). + +=head1 RETURN VALUES + +See description. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> + +=cut diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod new file mode 100644 index 000000000000..48c6b15db78f --- /dev/null +++ b/doc/ssl/SSL_get_error.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +SSL_get_error - obtain result code for TLS/SSL I/O operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_error(const SSL *ssl, int ret); + +=head1 DESCRIPTION + +SSL_get_error() returns a result code (suitable for the C "switch" +statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), +SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by +that TLS/SSL I/O function must be passed to SSL_get_error() in parameter +B<ret>. + +In addition to B<ssl> and B<ret>, SSL_get_error() inspects the +current thread's OpenSSL error queue. Thus, SSL_get_error() must be +used in the same thread that performed the TLS/SSL I/O operation, and no +other OpenSSL function calls should appear in between. The current +thread's error queue must be empty before the TLS/SSL I/O operation is +attempted, or SSL_get_error() will not work reliably. + +=head1 RETURN VALUES + +The following return values can currently occur: + +=over 4 + +=item SSL_ERROR_NONE + +The TLS/SSL I/O operation completed. This result code is returned +if and only if B<ret E<gt> 0>. + +=item SSL_ERROR_ZERO_RETURN + +The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 +or TLS 1.0, this result code is returned only if a closure +alert has occurred in the protocol, i.e. if the connection has been +closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN> +does not necessarily indicate that the underlying transport +has been closed. + +=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE + +The operation did not complete; the same TLS/SSL I/O function should be +called again later. If, by then, the underlying B<BIO> has data +available for reading (if the result code is B<SSL_ERROR_WANT_READ>) +or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL +protocol progress will take place, i.e. at least part of an TLS/SSL +record will be read or written. Note that the retry may again lead to +a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition. +There is no fixed upper limit for the number of iterations that +may be necessary until progress becomes visible at application +protocol level. + +For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or +poll() on the underlying socket can be used to find out when the +TLS/SSL I/O function should be retried. + +Caveat: Any TLS/SSL I/O function can lead to either of +B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular, +SSL_read() or SSL_peek() may want to write data and SSL_write() may want +to read data. This is mainly because TLS/SSL handshakes may occur at any +time during the protocol (initiated by either the client or the server); +SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. + +=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT + +The operation did not complete; the same TLS/SSL I/O function should be +called again later. The underlying BIO was not connected yet to the peer +and the call would block in connect()/accept(). The SSL function should be +called again when the connection is established. These messages can only +appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively. +In order to find out, when the connection has been successfully established, +on many platforms select() or poll() for writing on the socket file descriptor +can be used. + +=item SSL_ERROR_WANT_X509_LOOKUP + +The operation did not complete because an application callback set by +SSL_CTX_set_client_cert_cb() has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. + +=item SSL_ERROR_SYSCALL + +Some I/O error occurred. The OpenSSL error queue may contain more +information on the error. If the error queue is empty +(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more +about the error: If B<ret == 0>, an EOF was observed that violates +the protocol. If B<ret == -1>, the underlying B<BIO> reported an +I/O error (for socket I/O on Unix systems, consult B<errno> for details). + +=item SSL_ERROR_SSL + +A failure in the SSL library occurred, usually a protocol error. The +OpenSSL error queue contains more information on the error. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<err(3)|err(3)> + +=head1 HISTORY + +SSL_get_error() was added in SSLeay 0.8. + +=cut diff --git a/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod new file mode 100644 index 000000000000..165c6a5b2cae --- /dev/null +++ b/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure +from X509_STORE_CTX + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_ex_data_X509_STORE_CTX_idx(void); + +=head1 DESCRIPTION + +SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which +the pointer to the SSL object is stored into the X509_STORE_CTX object. + +=head1 NOTES + +Whenever a X509_STORE_CTX object is created for the verification of the +peers certificate during a handshake, a pointer to the SSL object is +stored into the X509_STORE_CTX object to identify the connection affected. +To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can +be used with the correct index. This index is globally the same for all +X509_STORE_CTX objects and can be retrieved using +SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when +SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application +program directly or indirectly during other SSL setup functions or during +the handshake. + +The value depends on other index values defined for X509_STORE_CTX objects +before the SSL index is created. + +=head1 RETURN VALUES + +=over 4 + +=item E<gt>=0 + +The index value to access the pointer. + +=item E<lt>0 + +An error occurred, check the error stack for a detailed error message. + +=back + +=head1 EXAMPLES + +The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to +access the SSL object for the connection to be accessed during the +verify_callback() when checking the peers certificate. Please check +the example in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/doc/ssl/SSL_get_ex_new_index.pod b/doc/ssl/SSL_get_ex_new_index.pod new file mode 100644 index 000000000000..228d23d8c0bb --- /dev/null +++ b/doc/ssl/SSL_get_ex_new_index.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_set_ex_data(SSL *ssl, int idx, void *arg); + + void *SSL_get_ex_data(const SSL *ssl, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into +the B<ssl> object. + +SSL_get_ex_data() is used to retrieve the information for B<idx> from +B<ssl>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 EXAMPLES + +An example on how to use the functionality is included in the example +verify_callback() in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/doc/ssl/SSL_get_fd.pod b/doc/ssl/SSL_get_fd.pod new file mode 100644 index 000000000000..89260b522ca2 --- /dev/null +++ b/doc/ssl/SSL_get_fd.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_get_fd - get file descriptor linked to an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_fd(const SSL *ssl); + int SSL_get_rfd(const SSL *ssl); + int SSL_get_wfd(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_fd() returns the file descriptor which is linked to B<ssl>. +SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the +read or the write channel, which can be different. If the read and the +write channel are different, SSL_get_fd() will return the file descriptor +of the read channel. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item -1 + +The operation failed, because the underlying BIO is not of the correct type +(suitable for file descriptors). + +=item E<gt>=0 + +The file descriptor linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_get_peer_cert_chain.pod b/doc/ssl/SSL_get_peer_cert_chain.pod new file mode 100644 index 000000000000..49fb88f86faf --- /dev/null +++ b/doc/ssl/SSL_get_peer_cert_chain.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_get_peer_cert_chain - get the X509 certificate chain of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACKOF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_cert_chain() returns a pointer to STACKOF(X509) certificates +forming the certificate chain of the peer. If called on the client side, +the stack also contains the peer's certificate; if called on the server +side, the peer's certificate must be obtained separately using +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. +If the peer did not present a certificate, NULL is returned. + +=head1 NOTES + +The peer certificate chain is not necessarily available after reusing +a session, in which case a NULL pointer is returned. + +The reference count of the STACKOF(X509) object is not incremented. +If the corresponding session is freed, the pointer must not be used +any longer. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No certificate was presented by the peer or no connection was established +or the certificate chain is no longer available when a session is reused. + +=item Pointer to a STACKOF(X509) + +The return value points to the certificate chain presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)> + +=cut diff --git a/doc/ssl/SSL_get_peer_certificate.pod b/doc/ssl/SSL_get_peer_certificate.pod new file mode 100644 index 000000000000..ef7c8be18079 --- /dev/null +++ b/doc/ssl/SSL_get_peer_certificate.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_get_peer_certificate - get the X509 certificate of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_get_peer_certificate(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_certificate() returns a pointer to the X509 certificate the +peer presented. If the peer did not present a certificate, NULL is returned. + +=head1 NOTES + +Due to the protocol definition, a TLS/SSL server will always send a +certificate, if present. A client will only send a certificate when +explicitly requested to do so by the server (see +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>). If an anonymous cipher +is used, no certificates are sent. + +That a certificate is returned does not indicate information about the +verification state, use L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> +to check the verification state. + +The reference count of the X509 object is incremented by one, so that it +will not be destroyed when the session containing the peer certificate is +freed. The X509 object must be explicitly freed using X509_free(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No certificate was presented by the peer or no connection was established. + +=item Pointer to an X509 certificate + +The return value points to the certificate presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/doc/ssl/SSL_get_rbio.pod b/doc/ssl/SSL_get_rbio.pod new file mode 100644 index 000000000000..3d98233cacee --- /dev/null +++ b/doc/ssl/SSL_get_rbio.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +SSL_get_rbio - get BIO linked to an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + BIO *SSL_get_rbio(SSL *ssl); + BIO *SSL_get_wbio(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the +read or the write channel, which can be different. The reference count +of the BIO is not incremented. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No BIO was connected to the SSL object + +=item Any other pointer + +The BIO linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_get_session.pod b/doc/ssl/SSL_get_session.pod new file mode 100644 index 000000000000..0c41caa922ab --- /dev/null +++ b/doc/ssl/SSL_get_session.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_get_session - retrieve TLS/SSL session data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *SSL_get_session(const SSL *ssl); + SSL_SESSION *SSL_get0_session(const SSL *ssl); + SSL_SESSION *SSL_get1_session(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in +B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so +that the pointer can become invalid by other operations. + +SSL_get0_session() is the same as SSL_get_session(). + +SSL_get1_session() is the same as SSL_get_session(), but the reference +count of the B<SSL_SESSION> is incremented by one. + +=head1 NOTES + +The ssl session contains all information required to re-establish the +connection without a new handshake. + +SSL_get0_session() returns a pointer to the actual session. As the +reference counter is not incremented, the pointer is only valid while +the connection is in use. If L<SSL_clear(3)|SSL_clear(3)> or +L<SSL_free(3)|SSL_free(3)> is called, the session may be removed completely +(if considered bad), and the pointer obtained will become invalid. Even +if the session is valid, it can be removed at any time due to timeout +during L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>. + +If the data is to be kept, SSL_get1_session() will increment the reference +count, so that the session will not be implicitly removed by other operations +but stays in memory. In order to remove the session +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> must be explicitly called once +to decrement the reference count again. + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +There is no session available in B<ssl>. + +=item Pointer to an SSL + +The return value points to the data of an SSL session. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>, +L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/doc/ssl/SSL_get_verify_result.pod b/doc/ssl/SSL_get_verify_result.pod new file mode 100644 index 000000000000..55b56a53f92e --- /dev/null +++ b/doc/ssl/SSL_get_verify_result.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_get_verify_result - get result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_verify_result(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_verify_result() returns the result of the verification of the +X509 certificate presented by the peer, if any. + +=head1 NOTES + +SSL_get_verify_result() can only return one error code while the verification +of a certificate can fail because of many reasons at the same time. Only +the last verification error that occurred during the processing is available +from SSL_get_verify_result(). + +The verification result is part of the established session and is restored +when a session is reused. + +=head1 BUGS + +If no peer certificate was presented, the returned result code is +X509_V_OK. This is because no verification error occurred, it does however +not indicate success. SSL_get_verify_result() is only useful in connection +with L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. + +=head1 RETURN VALUES + +The following return values can currently occur: + +=over 4 + +=item X509_V_OK + +The verification succeeded or no peer certificate was presented. + +=item Any other value + +Documented in L<verify(1)|verify(1)>. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<verify(1)|verify(1)> + +=cut diff --git a/doc/ssl/SSL_get_version.pod b/doc/ssl/SSL_get_version.pod new file mode 100644 index 000000000000..cc271db2c534 --- /dev/null +++ b/doc/ssl/SSL_get_version.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +SSL_get_version - get the protocol version of a connection. + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_get_version(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_cipher_version() returns the name of the protocol used for the +connection B<ssl>. + +=head1 RETURN VALUES + +The following strings can occur: + +=over 4 + +=item SSLv2 + +The connection uses the SSLv2 protocol. + +=item SSLv3 + +The connection uses the SSLv3 protocol. + +=item TLSv1 + +The connection uses the TLSv1 protocol. + +=item unknown + +This indicates that no version has been set (no connection established). + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_library_init.pod b/doc/ssl/SSL_library_init.pod new file mode 100644 index 000000000000..ecf3c4858e52 --- /dev/null +++ b/doc/ssl/SSL_library_init.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms +- initialize SSL library by registering algorithms + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_library_init(void); + #define OpenSSL_add_ssl_algorithms() SSL_library_init() + #define SSLeay_add_ssl_algorithms() SSL_library_init() + +=head1 DESCRIPTION + +SSL_library_init() registers the available ciphers and digests. + +OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms +for SSL_library_init(). + +=head1 NOTES + +SSL_library_init() must be called before any other action takes place. + +=head1 WARNING + +SSL_library_init() only registers ciphers. Another important initialization +is the seeding of the PRNG (Pseudo Random Number Generator), which has to +be performed separately. + +=head1 EXAMPLES + +A typical TLS/SSL application will start with the library initialization, +will provide readable error messages and will seed the PRNG. + + SSL_load_error_strings(); /* readable error messages */ + SSL_library_init(); /* initialize library */ + actions_to_seed_PRNG(); + +=head1 RETURN VALUES + +SSL_library_init() always returns "1", so it is safe to discard the return +value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>, +L<RAND_add(3)|RAND_add(3)> + +=cut diff --git a/doc/ssl/SSL_load_client_CA_file.pod b/doc/ssl/SSL_load_client_CA_file.pod new file mode 100644 index 000000000000..02527dc2edc8 --- /dev/null +++ b/doc/ssl/SSL_load_client_CA_file.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_load_client_CA_file - load certificate names from file + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); + +=head1 DESCRIPTION + +SSL_load_client_CA_file() reads certificates from B<file> and returns +a STACK_OF(X509_NAME) with the subject names found. + +=head1 NOTES + +SSL_load_client_CA_file() reads a file of PEM formatted certificates and +extracts the X509_NAMES of the certificates found. While the name suggests +the specific usage as support function for +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +it is not limited to CA certificates. + +=head1 EXAMPLES + +Load names of CAs from file and use it as a client CA list: + + SSL_CTX *ctx; + STACK_OF(X509_NAME) *cert_names; + + ... + cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); + if (cert_names != NULL) + SSL_CTX_set_client_CA_list(ctx, cert_names); + else + error_handling(); + ... + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The operation failed, check out the error stack for the reason. + +=item Pointer to STACK_OF(X509_NAME) + +Pointer to the subject names of the successfully read certificates. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> + +=cut diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod new file mode 100644 index 000000000000..25300e978f02 --- /dev/null +++ b/doc/ssl/SSL_new.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_new - create a new SSL structure for a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL *SSL_new(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_new() creates a new B<SSL> structure which is needed to hold the +data for a TLS/SSL connection. The new structure inherits the settings +of the underlying context B<ctx>: connection method (SSLv2/v3/TLSv1), +options, verification settings, timeout settings. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL structure failed. Check the error stack to +find out the reason. + +=item Pointer to an SSL structure + +The return value points to an allocated SSL structure. + +=back + +=head1 SEE ALSO + +L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, +L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_pending.pod b/doc/ssl/SSL_pending.pod new file mode 100644 index 000000000000..43f2874e8b6a --- /dev/null +++ b/doc/ssl/SSL_pending.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_pending - obtain number of readable bytes buffered in an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_pending(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_pending() returns the number of bytes which are available inside +B<ssl> for immediate read. + +=head1 NOTES + +Data are received in blocks from the peer. Therefore data can be buffered +inside B<ssl> and are ready for immediate retrieval with +L<SSL_read(3)|SSL_read(3)>. + +=head1 RETURN VALUES + +The number of bytes pending is returned. + +=head1 BUGS + +SSL_pending() takes into account only bytes from the TLS/SSL record +that is currently being processed (if any). If the B<SSL> object's +I<read_ahead> flag is set, additional protocol bytes may have been +read containing more TLS/SSL records; these are ignored by +SSL_pending(). + +Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type +of pending data is application data. + +=head1 SEE ALSO + +L<SSL_read(3)|SSL_read(3)>, L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod new file mode 100644 index 000000000000..f6c37f77e491 --- /dev/null +++ b/doc/ssl/SSL_read.pod @@ -0,0 +1,118 @@ +=pod + +=head1 NAME + +SSL_read - read bytes from a TLS/SSL connection. + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_read(SSL *ssl, void *buf, int num); + +=head1 DESCRIPTION + +SSL_read() tries to read B<num> bytes from the specified B<ssl> into the +buffer B<buf>. + +=head1 NOTES + +If necessary, SSL_read() will negotiate a TLS/SSL session, if +not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or +L<SSL_accept(3)|SSL_accept(3)>. If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_read() operation. The behaviour of SSL_read() depends on the +underlying BIO. + +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is being done by calling +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() +before the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)> +function. + +SSL_read() works based on the SSL/TLS records. The data are received in +records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a +record has been completely received, it can be processed (decryption and +check of integrity). Therefore data that was not retrieved at the last +call of SSL_read() can still be buffered inside the SSL layer and will be +retrieved on the next call to SSL_read(). If B<num> is higher than the +number of bytes buffered, SSL_read() will return with the bytes buffered. +If no more bytes are in the buffer, SSL_read() will trigger the processing +of the next record. Only when the record has been received and processed +completely, SSL_read() will return reporting success. At most the contents +of the record will be returned. As the size of an SSL/TLS record may exceed +the maximum packet size of the underlying transport (e.g. TCP), it may +be necessary to read several packets from the transport layer before the +record is complete and SSL_read() can succeed. + +If the underlying BIO is B<blocking>, SSL_read() will only return, once the +read operation has been finished or an error occurred, except when a +renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. +This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. + +If the underlying BIO is B<non-blocking>, SSL_read() will also return +when the underlying BIO could not satisfy the needs of SSL_read() +to continue the operation. In this case a call to +L<SSL_get_error(3)|SSL_get_error(3)> with the +return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a +call to SSL_read() can also cause write operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_read(). The action depends on the underlying BIO. When using a +non-blocking socket, nothing is to be done, but select() can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. + +=head1 WARNING + +When an SSL_read() operation has to be repeated because of +B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated +with the same arguments. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt>0 + +The read operation was successful; the return value is the number of +bytes actually read from the TLS/SSL connection. + +=item 0 + +The read operation was not successful. The reason may either be a clean +shutdown due to a "close notify" alert sent by the peer (in which case +the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set +(see L<SSL_shutdown(3)|SSL_shutdown(3)>, +L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>). It is also possible, that +the peer simply shut down the underlying transport and the shutdown is +incomplete. Call SSL_get_error() with the return value B<ret> to find out, +whether an error occurred or the connection was shut down cleanly +(SSL_ERROR_ZERO_RETURN). + +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can +only be detected, whether the underlying connection was closed. It cannot +be checked, whether the closure was initiated by the peer or by something +else. + +=item E<lt>0 + +The read operation was not successful, because either an error occurred +or action must be taken by the calling process. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, +L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_rstate_string.pod b/doc/ssl/SSL_rstate_string.pod new file mode 100644 index 000000000000..bdb8a1fcd55f --- /dev/null +++ b/doc/ssl/SSL_rstate_string.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_rstate_string(SSL *ssl); + const char *SSL_rstate_string_long(SSL *ssl); + +=head1 DESCRIPTION + +SSL_rstate_string() returns a 2 letter string indicating the current read state +of the SSL object B<ssl>. + +SSL_rstate_string_long() returns a string indicating the current read state of +the SSL object B<ssl>. + +=head1 NOTES + +When performing a read operation, the SSL/TLS engine must parse the record, +consisting of header and body. When working in a blocking environment, +SSL_rstate_string[_long]() should always return "RD"/"read done". + +This function should only seldom be needed in applications. + +=head1 RETURN VALUES + +SSL_rstate_string() and SSL_rstate_string_long() can return the following +values: + +=over 4 + +=item "RH"/"read header" + +The header of the record is being evaluated. + +=item "RB"/"read body" + +The body of the record is being evaluated. + +=item "RD"/"read done" + +The record has been completely processed. + +=item "unknown"/"unknown" + +The read state is unknown. This should never happen. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_session_reused.pod b/doc/ssl/SSL_session_reused.pod new file mode 100644 index 000000000000..da7d06264d04 --- /dev/null +++ b/doc/ssl/SSL_session_reused.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_session_reused - query whether a reused session was negotiated during handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_session_reused(SSL *ssl); + +=head1 DESCRIPTION + +Query, whether a reused session was negotiated during the handshake. + +=head1 NOTES + +During the negotiation, a client can propose to reuse a session. The server +then looks up the session in its cache. If both client and server agree +on the session, it will be reused and a flag is being set that can be +queried by the application. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +A new session was negotiated. + +=item 1 + +A session was reused. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> + +=cut diff --git a/doc/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod new file mode 100644 index 000000000000..67c9756d3fe5 --- /dev/null +++ b/doc/ssl/SSL_set_bio.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_set_bio - connect the SSL object with a BIO + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write +operations of the TLS/SSL (encrypted) side of B<ssl>. + +The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively. +If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour. + +If there was already a BIO connected to B<ssl>, BIO_free() will be called +(for both the reading and writing side, if different). + +=head1 RETURN VALUES + +SSL_set_bio() cannot fail. + +=head1 SEE ALSO + +L<SSL_get_rbio(3)|SSL_get_rbio(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_set_connect_state.pod b/doc/ssl/SSL_set_connect_state.pod new file mode 100644 index 000000000000..d88a057deffa --- /dev/null +++ b/doc/ssl/SSL_set_connect_state.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in client or server mode + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_connect_state(SSL *ssl); + + void SSL_set_accept_state(SSL *ssl); + +=head1 DESCRIPTION + +SSL_set_connect_state() sets B<ssl> to work in client mode. + +SSL_set_accept_state() sets B<ssl> to work in server mode. + +=head1 NOTES + +When the SSL_CTX object was created with L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +it was either assigned a dedicated client method, a dedicated server +method, or a generic method, that can be used for both client and +server connections. (The method might have been changed with +L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> or +SSL_set_ssl_method().) + +When beginning a new handshake, the SSL engine must know whether it must +call the connect (client) or accept (server) routines. Even though it may +be clear from the method chosen, whether client or server mode was +requested, the handshake routines must be explicitly set. + +When using the L<SSL_connect(3)|SSL_connect(3)> or +L<SSL_accept(3)|SSL_accept(3)> routines, the correct handshake +routines are automatically set. When performing a transparent negotiation +using L<SSL_write(3)|SSL_write(3)> or L<SSL_read(3)|SSL_read(3)>, the +handshake routines must be explicitly set in advance using either +SSL_set_connect_state() or SSL_set_accept_state(). + +=head1 RETURN VALUES + +SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic +information. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_write(3)|SSL_write(3)>, L<SSL_read(3)|SSL_read(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, +L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> + +=cut diff --git a/doc/ssl/SSL_set_fd.pod b/doc/ssl/SSL_set_fd.pod new file mode 100644 index 000000000000..70291128fcec --- /dev/null +++ b/doc/ssl/SSL_set_fd.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_set_fd - connect the SSL object with a file descriptor + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set_fd(SSL *ssl, int fd); + int SSL_set_rfd(SSL *ssl, int fd); + int SSL_set_wfd(SSL *ssl, int fd); + +=head1 DESCRIPTION + +SSL_set_fd() sets the file descriptor B<fd> as the input/output facility +for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the +socket file descriptor of a network connection. + +When performing the operation, a B<socket BIO> is automatically created to +interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine +inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will +also have non-blocking behaviour. + +If there was already a BIO connected to B<ssl>, BIO_free() will be called +(for both the reading and writing side, if different). + +SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only +for the read channel or the write channel, which can be set independently. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed. Check the error stack to find out why. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod new file mode 100644 index 000000000000..5f54714ad86a --- /dev/null +++ b/doc/ssl/SSL_set_session.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set_session(SSL *ssl, SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_set_session() sets B<session> to be used when the TLS/SSL connection +is to be established. SSL_set_session() is only useful for TLS/SSL clients. +When the session is set, the reference count of B<session> is incremented +by 1. If the session is not reused, the reference count is decremented +again during SSL_connect(). Whether the session was reused can be queried +with the L<SSL_session_reused(3)|SSL_session_reused(3)> call. + +If there is already a session set inside B<ssl> (because it was set with +SSL_set_session() before or because the same B<ssl> was already used for +a connection), SSL_SESSION_free() will be called for that session. + +=head1 NOTES + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed; check the error stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_get_session(3)|SSL_get_session(3)>, +L<SSL_session_reused(3)|SSL_session_reused(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> + +=cut diff --git a/doc/ssl/SSL_set_shutdown.pod b/doc/ssl/SSL_set_shutdown.pod new file mode 100644 index 000000000000..011a022a12c3 --- /dev/null +++ b/doc/ssl/SSL_set_shutdown.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_shutdown(SSL *ssl, int mode); + + int SSL_get_shutdown(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>. + +SSL_get_shutdown() returns the shutdown mode of B<ssl>. + +=head1 NOTES + +The shutdown state of an ssl connection is a bitmask of: + +=over 4 + +=item 0 + +No shutdown setting, yet. + +=item SSL_SENT_SHUTDOWN + +A "close notify" shutdown alert was sent to the peer, the connection is being +considered closed and the session is closed and correct. + +=item SSL_RECEIVED_SHUTDOWN + +A shutdown alert was received form the peer, either a normal "close notify" +or a fatal error. + +=back + +SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. + +The shutdown state of the connection is used to determine the state of +the ssl session. If the session is still open, when +L<SSL_clear(3)|SSL_clear(3)> or L<SSL_free(3)|SSL_free(3)> is called, +it is considered bad and removed according to RFC2246. +The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the "close notify" +alert but to not wait for the peer's answer, when the underlying connection +is closed). +SSL_set_shutdown() can be used to set this state without sending a +close alert to the peer (see L<SSL_shutdown(3)|SSL_shutdown(3)>). + +If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set, +for setting SSL_SENT_SHUTDOWN the application must however still call +L<SSL_shutdown(3)|SSL_shutdown(3)> or SSL_set_shutdown() itself. + +=head1 RETURN VALUES + +SSL_set_shutdown() does not return diagnostic information. + +SSL_get_shutdown() returns the current setting. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, +L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> + +=cut diff --git a/doc/ssl/SSL_set_verify_result.pod b/doc/ssl/SSL_set_verify_result.pod new file mode 100644 index 000000000000..04ab101aad2e --- /dev/null +++ b/doc/ssl/SSL_set_verify_result.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_set_verify_result - override result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_verify_result(SSL *ssl, long verify_result); + +=head1 DESCRIPTION + +SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the +result of the verification of the X509 certificate presented by the peer, +if any. + +=head1 NOTES + +SSL_set_verify_result() overrides the verification result. It only changes +the verification result of the B<ssl> object. It does not become part of the +established session, so if the session is to be reused later, the original +value will reappear. + +The valid codes for B<verify_result> are documented in L<verify(1)|verify(1)>. + +=head1 RETURN VALUES + +SSL_set_verify_result() does not provide a return value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<verify(1)|verify(1)> + +=cut diff --git a/doc/ssl/SSL_shutdown.pod b/doc/ssl/SSL_shutdown.pod new file mode 100644 index 000000000000..89911acbcac8 --- /dev/null +++ b/doc/ssl/SSL_shutdown.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +SSL_shutdown - shut down a TLS/SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_shutdown(SSL *ssl); + +=head1 DESCRIPTION + +SSL_shutdown() shuts down an active TLS/SSL connection. It sends the +"close notify" shutdown alert to the peer. + +=head1 NOTES + +SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. +Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and +a currently open session is considered closed and good and will be kept in the +session cache for further reuse. + +The shutdown procedure consists of 2 steps: the sending of the "close notify" +shutdown alert and the reception of the peer's "close notify" shutdown +alert. According to the TLS standard, it is acceptable for an application +to only send its shutdown alert and then close the underlying connection +without waiting for the peer's response (this way resources can be saved, +as the process can already terminate or serve another connection). +When the underlying connection shall be used for more communications, the +complete shutdown procedure (bidirectional "close notify" alerts) must be +performed, so that the peers stay synchronized. + +SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step +behaviour. + +=over 4 + +=item When the application is the first party to send the "close notify" +alert, SSL_shutdown() will only send the alert and then set the +SSL_SENT_SHUTDOWN flag (so that the session is considered good and will +be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional +shutdown is enough (the underlying connection shall be closed anyway), this +first call to SSL_shutdown() is sufficient. In order to complete the +bidirectional shutdown handshake, SSL_shutdown() must be called again. +The second call will make SSL_shutdown() wait for the peer's "close notify" +shutdown alert. On success, the second call to SSL_shutdown() will return +with 1. + +=item If the peer already sent the "close notify" alert B<and> it was +already processed implicitly inside another function +(L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. +SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN +flag and will immediately return with 1. +Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the +SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call. + +=back + +It is therefore recommended, to check the return value of SSL_shutdown() +and call SSL_shutdown() again, if the bidirectional shutdown is not yet +complete (return value of the first call is 0). As the shutdown is not +specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on +the first call. + +The behaviour of SSL_shutdown() additionally depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the +handshake step has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return +when the underlying BIO could not satisfy the needs of SSL_shutdown() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_shutdown(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +SSL_shutdown() can be modified to only set the connection to "shutdown" +state but not actually send the "close notify" alert messages, +see L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>. +When "quiet shutdown" is enabled, SSL_shutdown() will always succeed +and return 1. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The shutdown was successfully completed. The "close notify" alert was sent +and the peer's "close notify" alert was received. + +=item 0 + +The shutdown is not yet finished. Call SSL_shutdown() for a second time, +if a bidirectional shutdown shall be performed. +The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an +erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. + +=item -1 + +The shutdown was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. It can also occur if +action is need to continue the operation for non-blocking BIOs. +Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, +L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>, +L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/SSL_state_string.pod b/doc/ssl/SSL_state_string.pod new file mode 100644 index 000000000000..fe25d47c71a3 --- /dev/null +++ b/doc/ssl/SSL_state_string.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_state_string(const SSL *ssl); + const char *SSL_state_string_long(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_state_string() returns a 6 letter string indicating the current state +of the SSL object B<ssl>. + +SSL_state_string_long() returns a string indicating the current state of +the SSL object B<ssl>. + +=head1 NOTES + +During its use, an SSL objects passes several states. The state is internally +maintained. Querying the state information is not very informative before +or when a connection has been established. It however can be of significant +interest during the handshake. + +When using non-blocking sockets, the function call performing the handshake +may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, +so that SSL_state_string[_long]() may be called. + +For both blocking or non-blocking sockets, the details state information +can be used within the info_callback function set with the +SSL_set_info_callback() call. + +=head1 RETURN VALUES + +Detailed description of possible states to be included later. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> + +=cut diff --git a/doc/ssl/SSL_want.pod b/doc/ssl/SSL_want.pod new file mode 100644 index 000000000000..c0059c0d4a56 --- /dev/null +++ b/doc/ssl/SSL_want.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup - obtain state information TLS/SSL I/O operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_want(const SSL *ssl); + int SSL_want_nothing(const SSL *ssl); + int SSL_want_read(const SSL *ssl); + int SSL_want_write(const SSL *ssl); + int SSL_want_x509_lookup(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_want() returns state information for the SSL object B<ssl>. + +The other SSL_want_*() calls are shortcuts for the possible states returned +by SSL_want(). + +=head1 NOTES + +SSL_want() examines the internal state information of the SSL object. Its +return values are similar to that of L<SSL_get_error(3)|SSL_get_error(3)>. +Unlike L<SSL_get_error(3)|SSL_get_error(3)>, which also evaluates the +error queue, the results are obtained by examining an internal state flag +only. The information must therefore only be used for normal operation under +non-blocking I/O. Error conditions are not handled and must be treated +using L<SSL_get_error(3)|SSL_get_error(3)>. + +The result returned by SSL_want() should always be consistent with +the result of L<SSL_get_error(3)|SSL_get_error(3)>. + +=head1 RETURN VALUES + +The following return values can currently occur for SSL_want(): + +=over 4 + +=item SSL_NOTHING + +There is no data to be written or to be read. + +=item SSL_WRITING + +There are data in the SSL buffer that must be written to the underlying +B<BIO> layer in order to complete the actual SSL_*() operation. +A call to L<SSL_get_error(3)|SSL_get_error(3)> should return +SSL_ERROR_WANT_WRITE. + +=item SSL_READING + +More data must be read from the underlying B<BIO> layer in order to +complete the actual SSL_*() operation. +A call to L<SSL_get_error(3)|SSL_get_error(3)> should return +SSL_ERROR_WANT_READ. + +=item SSL_X509_LOOKUP + +The operation did not complete because an application callback set by +SSL_CTX_set_client_cert_cb() has asked to be called again. +A call to L<SSL_get_error(3)|SSL_get_error(3)> should return +SSL_ERROR_WANT_X509_LOOKUP. + +=back + +SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup() +return 1, when the corresponding condition is true or 0 otherwise. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<err(3)|err(3)>, L<SSL_get_error(3)|SSL_get_error(3)> + +=cut diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod new file mode 100644 index 000000000000..e013c12d5254 --- /dev/null +++ b/doc/ssl/SSL_write.pod @@ -0,0 +1,109 @@ +=pod + +=head1 NAME + +SSL_write - write bytes to a TLS/SSL connection. + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_write(SSL *ssl, const void *buf, int num); + +=head1 DESCRIPTION + +SSL_write() writes B<num> bytes from the buffer B<buf> into the specified +B<ssl> connection. + +=head1 NOTES + +If necessary, SSL_write() will negotiate a TLS/SSL session, if +not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or +L<SSL_accept(3)|SSL_accept(3)>. If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_write() operation. The behaviour of SSL_write() depends on the +underlying BIO. + +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is being done by calling +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() +before the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function. + +If the underlying BIO is B<blocking>, SSL_write() will only return, once the +write operation has been finished or an error occurred, except when a +renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. +This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. + +If the underlying BIO is B<non-blocking>, SSL_write() will also return, +when the underlying BIO could not satisfy the needs of SSL_write() +to continue the operation. In this case a call to +L<SSL_get_error(3)|SSL_get_error(3)> with the +return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a +call to SSL_write() can also cause read operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_write(). The action depends on the underlying BIO. When using a +non-blocking socket, nothing is to be done, but select() can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. + +SSL_write() will only return with success, when the complete contents +of B<buf> of length B<num> has been written. This default behaviour +can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set, +SSL_write() will also return with success, when a partial write has been +successfully completed. In this case the SSL_write() operation is considered +completed. The bytes are sent and a new SSL_write() operation with a new +buffer (with the already sent bytes removed) must be started. +A partial write is performed with the size of a message block, which is +16kB for SSLv3/TLSv1. + +=head1 WARNING + +When an SSL_write() operation has to be repeated because of +B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated +with the same arguments. + +When calling SSL_write() with num=0 bytes to be sent the behaviour is +undefined. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt>0 + +The write operation was successful, the return value is the number of +bytes actually written to the TLS/SSL connection. + +=item 0 + +The write operation was not successful. Probably the underlying connection +was closed. Call SSL_get_error() with the return value B<ret> to find out, +whether an error occurred or the connection was shut down cleanly +(SSL_ERROR_ZERO_RETURN). + +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can +only be detected, whether the underlying connection was closed. It cannot +be checked, why the closure happened. + +=item E<lt>0 + +The write operation was not successful, because either an error occurred +or action must be taken by the calling process. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> + +=cut diff --git a/doc/ssl/d2i_SSL_SESSION.pod b/doc/ssl/d2i_SSL_SESSION.pod new file mode 100644 index 000000000000..81d276477f9f --- /dev/null +++ b/doc/ssl/d2i_SSL_SESSION.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); + int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); + +=head1 DESCRIPTION + +d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS +session, stored as binary data at location B<pp> with length B<length>, into +an SSL_SESSION object. + +i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 +representation and stores it into the memory location pointed to by B<pp>. +The length of the resulting ASN1 representation is returned. If B<pp> is +the NULL pointer, only the length is calculated and returned. + +=head1 NOTES + +The SSL_SESSION object is built from several malloc()ed parts, it can +therefore not be moved, copied or stored directly. In order to store +session data on disk or into a database, it must be transformed into +a binary ASN1 representation. + +When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically +allocated. The reference count is 1, so that the session must be +explicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +unless the SSL_SESSION object is completely taken over, when being called +inside the get_session_cb() (see +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be +large enough to hold the binary representation of the session. There is no +known limit on the size of the created ASN1 representation, so the necessary +amount of space should be obtained by first calling i2d_SSL_SESSION() with +B<pp=NULL>, and obtain the size needed, then allocate the memory and +call i2d_SSL_SESSION() again. + +=head1 RETURN VALUES + +d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION +object. In case of failure the NULL-pointer is returned and the error message +can be retrieved from the error stack. + +i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. +When the session is not valid, B<0> is returned and no operation is performed. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod new file mode 100644 index 000000000000..266697d22164 --- /dev/null +++ b/doc/ssl/ssl.pod @@ -0,0 +1,736 @@ + +=pod + +=head1 NAME + +SSL - OpenSSL SSL/TLS library + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and +Transport Layer Security (TLS v1) protocols. It provides a rich API which is +documented here. + +At first the library must be initialized; see +L<SSL_library_init(3)|SSL_library_init(3)>. + +Then an B<SSL_CTX> object is created as a framework to establish +TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>). +Various options regarding certificates, algorithms etc. can be set +in this object. + +When a network connection has been created, it can be assigned to an +B<SSL> object. After the B<SSL> object has been created using +L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or +L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network +connection with the object. + +Then the TLS/SSL handshake is performed using +L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)> +respectively. +L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used +to read and write data on the TLS/SSL connection. +L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the +TLS/SSL connection. + +=head1 DATA STRUCTURES + +Currently the OpenSSL B<ssl> library functions deals with the following data +structures: + +=over 4 + +=item B<SSL_METHOD> (SSL Method) + +That's a dispatch structure describing the internal B<ssl> library +methods/functions which implement the various protocol versions (SSLv1, SSLv2 +and TLSv1). It's needed to create an B<SSL_CTX>. + +=item B<SSL_CIPHER> (SSL Cipher) + +This structure holds the algorithm information for a particular cipher which +are a core part of the SSL/TLS protocol. The available ciphers are configured +on a B<SSL_CTX> basis and the actually used ones are then part of the +B<SSL_SESSION>. + +=item B<SSL_CTX> (SSL Context) + +That's the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +B<SSL> structures which are later created for the connections. + +=item B<SSL_SESSION> (SSL Session) + +This is a structure containing the current TLS/SSL session details for a +connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. + +=item B<SSL> (SSL Connection) + +That's the main SSL/TLS structure which is created by a server or client per +established connection. This actually is the core structure in the SSL API. +Under run-time the application usually deals with this structure which has +links to mostly all other structures. + +=back + + +=head1 HEADER FILES + +Currently the OpenSSL B<ssl> library provides the following C header files +containing the prototypes for the data structures and and functions: + +=over 4 + +=item B<ssl.h> + +That's the common header file for the SSL/TLS API. Include it into your +program to make the API of the B<ssl> library available. It internally +includes both more private SSL headers and headers from the B<crypto> library. +Whenever you need hard-core details on the internals of the SSL API, look +inside this header file. + +=item B<ssl2.h> + +That's the sub header file dealing with the SSLv2 protocol only. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=item B<ssl3.h> + +That's the sub header file dealing with the SSLv3 protocol only. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=item B<ssl23.h> + +That's the sub header file dealing with the combined use of the SSLv2 and +SSLv3 protocols. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=item B<tls1.h> + +That's the sub header file dealing with the TLSv1 protocol only. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=back + +=head1 API FUNCTIONS + +Currently the OpenSSL B<ssl> library exports 214 API functions. +They are documented in the following: + +=head2 DEALING WITH PROTOCOL METHODS + +Here we document the various API functions which deal with the SSL/TLS +protocol methods defined in B<SSL_METHOD> structures. + +=over 4 + +=item SSL_METHOD *B<SSLv2_client_method>(void); + +Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. + +=item SSL_METHOD *B<SSLv2_server_method>(void); + +Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. + +=item SSL_METHOD *B<SSLv2_method>(void); + +Constructor for the SSLv2 SSL_METHOD structure for combined client and server. + +=item SSL_METHOD *B<SSLv3_client_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. + +=item SSL_METHOD *B<SSLv3_server_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. + +=item SSL_METHOD *B<SSLv3_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for combined client and server. + +=item SSL_METHOD *B<TLSv1_client_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. + +=item SSL_METHOD *B<TLSv1_server_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. + +=item SSL_METHOD *B<TLSv1_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for combined client and server. + +=back + +=head2 DEALING WITH CIPHERS + +Here we document the various API functions which deal with the SSL/TLS +ciphers defined in B<SSL_CIPHER> structures. + +=over 4 + +=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); + +Write a string to I<buf> (with a maximum size of I<len>) containing a human +readable description of I<cipher>. Returns I<buf>. + +=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); + +Determine the number of bits in I<cipher>. Because of export crippled ciphers +there are two bits: The bits the algorithm supports in general (stored to +I<alg_bits>) and the bits which are actually used (the return value). + +=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); + +Return the internal name of I<cipher> as a string. These are the various +strings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> +definitions in the header files. + +=item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); + +Returns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" which indicates the +SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined +in the specification the first time). + +=back + +=head2 DEALING WITH PROTOCOL CONTEXTS + +Here we document the various API functions which deal with the SSL/TLS +protocol context defined in the B<SSL_CTX> structure. + +=over 4 + +=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); + +=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); + +=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); + +=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx); + +=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); + +=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); + +=item void B<SSL_CTX_free>(SSL_CTX *a); + +=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); + +=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); + +=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx); + +=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + +=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx); + +=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); + +=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx); + +=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); + +=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx); + +=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); + +=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); + +=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, char *CAfile, char *CApath); + +=item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); + +=item SSL_CTX *B<SSL_CTX_new>(SSL_METHOD *meth); + +=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); + +=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); + +=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); + +=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); + +=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); + +=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); + +=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx,t); + +=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); + +=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); + +=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); + +=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); + +=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); + +=item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); + +=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); + +=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) + +=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); + +=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); + +=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); + +=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) + +=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); + +=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); + +=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); + +=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); + +=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + +=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg); + +=item void B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); + +=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); + +=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); + +=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, SSL_METHOD *meth); + +=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); + +=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); + +=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); + +=item long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa); + +=item SSL_CTX_set_tmp_rsa_callback + +C<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));> + +Sets the callback which will be called when a temporary private key is +required. The B<C<export>> flag will be set if the reason for needing +a temp key is that an export ciphersuite is in use, in which case, +B<C<keylength>> will contain the required keylength in bits. Generate a key of +appropriate size (using ???) and return it. + +=item SSL_set_tmp_rsa_callback + +long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); + +The same as B<SSL_CTX_set_tmp_rsa_callback>, except it operates on an SSL +session instead of a context. + +=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) + +=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); + +=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); + +=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, char *file, int type); + +=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); + +=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); + +=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, char *file, int type); + +=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); + +=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); + +=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type); + +=back + +=head2 DEALING WITH SESSIONS + +Here we document the various API functions which deal with the SSL/TLS +sessions defined in the B<SSL_SESSION> structures. + +=over 4 + +=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b); + +=item void B<SSL_SESSION_free>(SSL_SESSION *ss); + +=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); + +=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx); + +=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s); + +=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s); + +=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a); + +=item SSL_SESSION *B<SSL_SESSION_new>(void); + +=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x); + +=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x); + +=item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); + +=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); + +=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); + +=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); + +=back + +=head2 DEALING WITH CONNECTIONS + +Here we document the various API functions which deal with the SSL/TLS +connection defined in the B<SSL> structure. + +=over 4 + +=item int B<SSL_accept>(SSL *ssl); + +=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); + +=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); + +=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); + +=item char *B<SSL_alert_desc_string>(int value); + +=item char *B<SSL_alert_desc_string_long>(int value); + +=item char *B<SSL_alert_type_string>(int value); + +=item char *B<SSL_alert_type_string_long>(int value); + +=item int B<SSL_check_private_key>(const SSL *ssl); + +=item void B<SSL_clear>(SSL *ssl); + +=item long B<SSL_clear_num_renegotiations>(SSL *ssl); + +=item int B<SSL_connect>(SSL *ssl); + +=item void B<SSL_copy_session_id>(SSL *t, const SSL *f); + +=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); + +=item int B<SSL_do_handshake>(SSL *ssl); + +=item SSL *B<SSL_dup>(SSL *ssl); + +=item STACK *B<SSL_dup_CA_list>(STACK *sk); + +=item void B<SSL_free>(SSL *ssl); + +=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl); + +=item char *B<SSL_get_app_data>(SSL *ssl); + +=item X509 *B<SSL_get_certificate>(const SSL *ssl); + +=item const char *B<SSL_get_cipher>(const SSL *ssl); + +=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits); + +=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n); + +=item char *B<SSL_get_cipher_name>(const SSL *ssl); + +=item char *B<SSL_get_cipher_version>(const SSL *ssl); + +=item STACK *B<SSL_get_ciphers>(const SSL *ssl); + +=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl); + +=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); + +=item long B<SSL_get_default_timeout>(const SSL *ssl); + +=item int B<SSL_get_error>(const SSL *ssl, int i); + +=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx); + +=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); + +=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item int B<SSL_get_fd>(const SSL *ssl); + +=item void (*B<SSL_get_info_callback>(const SSL *ssl);)() + +=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); + +=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); + +=item EVP_PKEY *B<SSL_get_privatekey>(SSL *ssl); + +=item int B<SSL_get_quiet_shutdown>(const SSL *ssl); + +=item BIO *B<SSL_get_rbio>(const SSL *ssl); + +=item int B<SSL_get_read_ahead>(const SSL *ssl); + +=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); + +=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); + +=item int B<SSL_get_shutdown>(const SSL *ssl); + +=item SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); + +=item int B<SSL_get_state>(const SSL *ssl); + +=item long B<SSL_get_time>(const SSL *ssl); + +=item long B<SSL_get_timeout>(const SSL *ssl); + +=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int,X509_STORE_CTX *) + +=item int B<SSL_get_verify_mode>(const SSL *ssl); + +=item long B<SSL_get_verify_result>(const SSL *ssl); + +=item char *B<SSL_get_version>(const SSL *ssl); + +=item BIO *B<SSL_get_wbio>(const SSL *ssl); + +=item int B<SSL_in_accept_init>(SSL *ssl); + +=item int B<SSL_in_before>(SSL *ssl); + +=item int B<SSL_in_connect_init>(SSL *ssl); + +=item int B<SSL_in_init>(SSL *ssl); + +=item int B<SSL_is_init_finished>(SSL *ssl); + +=item STACK *B<SSL_load_client_CA_file>(char *file); + +=item void B<SSL_load_error_strings>(void); + +=item SSL *B<SSL_new>(SSL_CTX *ctx); + +=item long B<SSL_num_renegotiations>(SSL *ssl); + +=item int B<SSL_peek>(SSL *ssl, void *buf, int num); + +=item int B<SSL_pending>(const SSL *ssl); + +=item int B<SSL_read>(SSL *ssl, void *buf, int num); + +=item int B<SSL_renegotiate>(SSL *ssl); + +=item char *B<SSL_rstate_string>(SSL *ssl); + +=item char *B<SSL_rstate_string_long>(SSL *ssl); + +=item long B<SSL_session_reused>(SSL *ssl); + +=item void B<SSL_set_accept_state>(SSL *ssl); + +=item void B<SSL_set_app_data>(SSL *ssl, char *arg); + +=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); + +=item int B<SSL_set_cipher_list>(SSL *ssl, char *str); + +=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); + +=item void B<SSL_set_connect_state>(SSL *ssl); + +=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); + +=item int B<SSL_set_fd>(SSL *ssl, int fd); + +=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) + +=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + +=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg); + +=item void B<SSL_set_options>(SSL *ssl, unsigned long op); + +=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); + +=item void B<SSL_set_read_ahead>(SSL *ssl, int yes); + +=item int B<SSL_set_rfd>(SSL *ssl, int fd); + +=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); + +=item void B<SSL_set_shutdown>(SSL *ssl, int mode); + +=item int B<SSL_set_ssl_method>(SSL *ssl, SSL_METHOD *meth); + +=item void B<SSL_set_time>(SSL *ssl, long t); + +=item void B<SSL_set_timeout>(SSL *ssl, long t); + +=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) + +=item void B<SSL_set_verify_result>(SSL *ssl, long arg); + +=item int B<SSL_set_wfd>(SSL *ssl, int fd); + +=item int B<SSL_shutdown>(SSL *ssl); + +=item int B<SSL_state>(const SSL *ssl); + +=item char *B<SSL_state_string>(const SSL *ssl); + +=item char *B<SSL_state_string_long>(const SSL *ssl); + +=item long B<SSL_total_renegotiations>(SSL *ssl); + +=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); + +=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); + +=item int B<SSL_use_PrivateKey_file>(SSL *ssl, char *file, int type); + +=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); + +=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); + +=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, char *file, int type); + +=item int B<SSL_use_certificate>(SSL *ssl, X509 *x); + +=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); + +=item int B<SSL_use_certificate_file>(SSL *ssl, char *file, int type); + +=item int B<SSL_version>(const SSL *ssl); + +=item int B<SSL_want>(const SSL *ssl); + +=item int B<SSL_want_nothing>(const SSL *ssl); + +=item int B<SSL_want_read>(const SSL *ssl); + +=item int B<SSL_want_write>(const SSL *ssl); + +=item int B<SSL_want_x509_lookup>(const SSL *ssl); + +=item int B<SSL_write>(SSL *ssl, const void *buf, int num); + +=back + +=head1 SEE ALSO + +L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, +L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>, +L<SSL_COMP_add_compression_method(3)|SSL_COMP_add_compression_method(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_ctrl(3)|SSL_CTX_ctrl(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, +L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, +L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, +L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_generate_session_id(3)|SSL_CTX_set_generate_session_id(3)>, +L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>, +L<SSL_CTX_set_max_cert_list(3)|SSL_CTX_set_max_cert_list(3)>, +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, +L<SSL_CTX_set_msg_callback(3)|SSL_CTX_set_msg_callback(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, +L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, +L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, +L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>, +L<SSL_get_error(3)|SSL_get_error(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, +L<SSL_get_fd(3)|SSL_get_fd(3)>, +L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, +L<SSL_get_rbio(3)|SSL_get_rbio(3)>, +L<SSL_get_session(3)|SSL_get_session(3)>, +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_get_version(3)|SSL_get_version(3)>, +L<SSL_library_init(3)|SSL_library_init(3)>, +L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, +L<SSL_new(3)|SSL_new(3)>, +L<SSL_pending(3)|SSL_pending(3)>, +L<SSL_read(3)|SSL_read(3)>, +L<SSL_rstate_string(3)|SSL_rstate_string(3)>, +L<SSL_session_reused(3)|SSL_session_reused(3)>, +L<SSL_set_bio(3)|SSL_set_bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_set_fd(3)|SSL_set_fd(3)>, +L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, +L<SSL_shutdown(3)|SSL_shutdown(3)>, +L<SSL_state_string(3)|SSL_state_string(3)>, +L<SSL_want(3)|SSL_want(3)>, +L<SSL_write(3)|SSL_write(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> + +=head1 HISTORY + +The L<ssl(3)|ssl(3)> document appeared in OpenSSL 0.9.2 + +=cut + |