diff options
Diffstat (limited to 'crypto/openssl/doc/ssl')
42 files changed, 1603 insertions, 82 deletions
diff --git a/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod b/crypto/openssl/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 0000000..2a98739 --- /dev/null +++ b/crypto/openssl/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 1 + +The operation succeeded. + +=item 0 + +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/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod b/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod new file mode 100644 index 0000000..4228225 --- /dev/null +++ b/crypto/openssl/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, char *parg); + long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); + + long SSL_ctrl(SSL *ssl, int cmd, long larg, char *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/crypto/openssl/doc/ssl/SSL_CTX_free.pod b/crypto/openssl/doc/ssl/SSL_CTX_free.pod index c716cde..55e592f 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_free.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_free.pod @@ -24,6 +24,8 @@ the certificates and keys. 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)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod index 0f63537..84a799f 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -58,7 +58,7 @@ 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 -explicitely be set using the +explicitly be set using the L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> family of functions. @@ -118,7 +118,7 @@ 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_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/crypto/openssl/doc/ssl/SSL_CTX_new.pod b/crypto/openssl/doc/ssl/SSL_CTX_new.pod index 1dae8b0..465220a 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_new.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_new.pod @@ -59,10 +59,6 @@ choice when compatibility is a concern. =back -If a generic method is used, it is necessary to explicitly set client or -server mode with L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> -or SSL_set_accept_state(). - 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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod index b6f15b4..6e0ef00 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -70,12 +70,16 @@ 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. +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_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod new file mode 100644 index 0000000..81286ee --- /dev/null +++ b/crypto/openssl/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(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 X505_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/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000..723fc14 --- /dev/null +++ b/crypto/openssl/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)(), + char *arg); + int (*callback)(); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_verify_callback() sets the verification callback function for +B<ctx>. SSL objects, that are created from B<ctx> inherit the setting valid at +the time, L<SSL_new(3)|SSL_new(3)> is called. B<arg> is currently ignored. + +=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 B<callback> is specified via +SSL_CTX_set_cert_verify_callback(), the supplied callback function is called +instead. By setting B<callback> to NULL, the default behaviour is restored. + +When the verification must be performed, B<callback> will be called with +the argument callback(X509_STORE_CTX *x509_store_ctx). The arguments B<arg> +that can be specified when setting B<callback> are currently ignored. + +B<callback> should return 1 to indicate verification success and 0 to +indicate verification failure. If SSL_VERIFY_PEER is set and B<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 B<x509_store_ctx>, so that the calling application will be informed +about the detailed result of the verification procedure! + +Within B<x509_store_ctx>, B<callback> has access to the B<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 + +It is possible to specify arguments to be passed to the verification callback. +Currently they are however not passed but ignored. + +The B<callback> function is not specified via a prototype, so that no +type checking takes place. + +=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)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod index 9a29eee..ed64f64 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -34,9 +34,25 @@ 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, the respective is valid for DSA ciphers. Ciphers using EDH need -a certificate and key and DH-parameters. +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 @@ -47,6 +63,8 @@ could be selected and 0 on complete failure. 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/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod index a5343a1..2b87f01 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -40,6 +40,12 @@ 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. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_info_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 0000000..63d0b8d --- /dev/null +++ b/crypto/openssl/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(SSL_CTX *ctx))(); + + void SSL_set_info_callback(SSL *ssl, void (*callback)()); + void (*SSL_get_info_callback(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/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod index 9a035bb..9822544 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_mode.pod @@ -37,6 +37,9 @@ The following mode changes are available: 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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod index 3dc7cc7..5842a31 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -17,10 +17,10 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man =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. +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. +Options already set before are not cleared! SSL_CTX_get_options() returns the options set for B<ctx>. @@ -32,7 +32,12 @@ 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. -During a handshake, the option settings of the SSL object used. When +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_modes(3)|SSL_CTX_set_modes(3)> and SSL_set_modes() 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. @@ -122,11 +127,27 @@ The following B<modifying> options are available: =item SSL_OP_SINGLE_DH_USE -Always create a new key when using temporary DH parameters. +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. +SSL_OP_SINGLE_DH_USE should therefore be enabled whenever +temporary/ephemeral DH parameters are used. =item SSL_OP_EPHEMERAL_RSA -Also use the temporary RSA key when doing RSA operations. +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_PKCS1_CHECK_1 @@ -142,11 +163,6 @@ If we accept a netscape connection, demand a client cert, have a non-self-sighed CA which does not have it's CA in netscape, and the browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta -=item SSL_OP_NON_EXPORT_FIRST - -On servers try to use non-export (stronger) ciphers first. This option does -not work under all circumstances (in the code it is declared "broken"). - =item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG ... @@ -174,7 +190,10 @@ 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(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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod new file mode 100644 index 0000000..1d0526d --- /dev/null +++ b/crypto/openssl/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(SSL_CTX *ctx); + + void SSL_set_quiet_shutdown(SSL *ssl, int mode); + int SSL_get_quiet_shutdown(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/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod index 8bbfc78..9aa6c6b 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -97,6 +97,7 @@ 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_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)>, diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod index 21faed1..e3de27c 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod @@ -37,7 +37,10 @@ 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 300 seconds. +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 @@ -50,6 +53,7 @@ SSL_CTX_get_timeout() returns the currently set timeout value. 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_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 0000000..29d1f8a --- /dev/null +++ b/crypto/openssl/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/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod new file mode 100644 index 0000000..f857759 --- /dev/null +++ b/crypto/openssl/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/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod index fc0b761..5bb21ca 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod @@ -59,14 +59,14 @@ The handshake will be continued regardless of the verification result. 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 as indicated by B<verify_callback>, the TLS/SSL handshake is +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 as indicated by B<verify_callback>, the TLS/SSL handshake is +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. @@ -92,6 +92,15 @@ B<Client mode:> ignored 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 @@ -278,6 +287,7 @@ 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)> diff --git a/crypto/openssl/doc/ssl/SSL_SESSION_free.pod b/crypto/openssl/doc/ssl/SSL_SESSION_free.pod index df30ccb..558de01 100644 --- a/crypto/openssl/doc/ssl/SSL_SESSION_free.pod +++ b/crypto/openssl/doc/ssl/SSL_SESSION_free.pod @@ -16,10 +16,40 @@ 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. -L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)> +=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/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod b/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod index cd33b73..ea3c2bc 100644 --- a/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod +++ b/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod @@ -58,6 +58,7 @@ If any of the function is passed the NULL pointer for the session B<s>, =head1 SEE ALSO L<ssl(3)|ssl(3)>, -L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(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/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod index 86f980d..ac6caf9 100644 --- a/crypto/openssl/doc/ssl/SSL_accept.pod +++ b/crypto/openssl/doc/ssl/SSL_accept.pod @@ -37,11 +37,6 @@ 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. -When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it -is necessary to call SSL_set_accept_state() -before calling SSL_accept() to explicitly switch the B<ssl> to server -mode. - =head1 RETURN VALUES The following return values can occur: diff --git a/crypto/openssl/doc/ssl/SSL_alert_type_string.pod b/crypto/openssl/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 0000000..7837589 --- /dev/null +++ b/crypto/openssl/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> + + char *SSL_alert_type_string(int value); + char *SSL_alert_type_string_long(int value); + + char *SSL_alert_desc_string(int value); + 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/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod index bcc1677..766f187 100644 --- a/crypto/openssl/doc/ssl/SSL_connect.pod +++ b/crypto/openssl/doc/ssl/SSL_connect.pod @@ -34,11 +34,6 @@ 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. -When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it -is necessary to call L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> -before calling SSL_connect() to explicitly switch the B<ssl> to client -mode. - =head1 RETURN VALUES The following return values can occur: diff --git a/crypto/openssl/doc/ssl/SSL_get_SSL_CTX.pod b/crypto/openssl/doc/ssl/SSL_get_SSL_CTX.pod new file mode 100644 index 0000000..52d0227 --- /dev/null +++ b/crypto/openssl/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(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/crypto/openssl/doc/ssl/SSL_get_default_timeout.pod b/crypto/openssl/doc/ssl/SSL_get_default_timeout.pod new file mode 100644 index 0000000..8d43b31 --- /dev/null +++ b/crypto/openssl/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(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/crypto/openssl/doc/ssl/SSL_get_error.pod b/crypto/openssl/doc/ssl/SSL_get_error.pod index d95eec7..f700bf0 100644 --- a/crypto/openssl/doc/ssl/SSL_get_error.pod +++ b/crypto/openssl/doc/ssl/SSL_get_error.pod @@ -69,13 +69,13 @@ 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 +=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(). The SSL function should be -called again when the connection is established. This messages can only -appear with a BIO_s_connect() BIO. +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. diff --git a/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod b/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod index 18d1db5..60635a9 100644 --- a/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod +++ b/crypto/openssl/doc/ssl/SSL_get_peer_certificate.pod @@ -19,7 +19,7 @@ peer presented. If the peer did not present a certificate, NULL is returned. Due to the protocol definition, a TLS/SSL server will always send a certificate, if present. A client will only send a certificate when -explicitely requested to do so by the server (see +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. diff --git a/crypto/openssl/doc/ssl/SSL_get_session.pod b/crypto/openssl/doc/ssl/SSL_get_session.pod index a0266e2..dd9aba4 100644 --- a/crypto/openssl/doc/ssl/SSL_get_session.pod +++ b/crypto/openssl/doc/ssl/SSL_get_session.pod @@ -37,8 +37,16 @@ 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 and the session will stay in memory until explicitly freed with -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, regardless of its state. +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 diff --git a/crypto/openssl/doc/ssl/SSL_new.pod b/crypto/openssl/doc/ssl/SSL_new.pod index 3b084e8..25300e9 100644 --- a/crypto/openssl/doc/ssl/SSL_new.pod +++ b/crypto/openssl/doc/ssl/SSL_new.pod @@ -38,6 +38,7 @@ The return value points to an allocated SSL structure. 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/crypto/openssl/doc/ssl/SSL_read.pod b/crypto/openssl/doc/ssl/SSL_read.pod index cc7aa1a..f6c37f7 100644 --- a/crypto/openssl/doc/ssl/SSL_read.pod +++ b/crypto/openssl/doc/ssl/SSL_read.pod @@ -25,11 +25,10 @@ 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 not the case if a generic -method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that +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() -must be used before the first call to an SSL_read() or -L<SSL_write(3)|SSL_write(3)> function). +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 @@ -84,9 +83,20 @@ bytes actually read from the TLS/SSL connection. =item 0 -The read operation was not successful, probably because no data was -available. Call SSL_get_error() with the return value B<ret> to find out, -whether an error occurred. +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 @@ -102,6 +112,7 @@ 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/crypto/openssl/doc/ssl/SSL_rstate_string.pod b/crypto/openssl/doc/ssl/SSL_rstate_string.pod new file mode 100644 index 0000000..6dbbb99 --- /dev/null +++ b/crypto/openssl/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> + + char *SSL_rstate_string(SSL *ssl); + 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/crypto/openssl/doc/ssl/SSL_session_reused.pod b/crypto/openssl/doc/ssl/SSL_session_reused.pod new file mode 100644 index 0000000..da7d062 --- /dev/null +++ b/crypto/openssl/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/crypto/openssl/doc/ssl/SSL_set_connect_state.pod b/crypto/openssl/doc/ssl/SSL_set_connect_state.pod index a8c4463..7adf8ad 100644 --- a/crypto/openssl/doc/ssl/SSL_set_connect_state.pod +++ b/crypto/openssl/doc/ssl/SSL_set_connect_state.pod @@ -14,9 +14,9 @@ SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in clie =head1 DESCRIPTION -SSL_set_connect_state() B<ssl> to work in client mode. +SSL_set_connect_state() sets B<ssl> to work in client mode. -SSL_set_accept_state() B<ssl> to work in server mode. +SSL_set_accept_state() sets B<ssl> to work in server mode. =head1 NOTES @@ -27,12 +27,17 @@ 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().) -In order to successfully accomplish the handshake, the SSL routines need -to know whether they should act in server or client mode. If the generic -method was used, this is not clear from the method itself and must be set -with either SSL_set_connect_state() or SSL_set_accept_state(). If these -routines are not called, the default value set when L<SSL_new(3)|SSL_new(3)> -is called is server mode. +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 @@ -42,6 +47,8 @@ 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_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_set_session.pod b/crypto/openssl/doc/ssl/SSL_set_session.pod index c4f7878..5f54714 100644 --- a/crypto/openssl/doc/ssl/SSL_set_session.pod +++ b/crypto/openssl/doc/ssl/SSL_set_session.pod @@ -16,12 +16,21 @@ 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(). +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: @@ -41,6 +50,8 @@ The operation succeeded. =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/crypto/openssl/doc/ssl/SSL_set_shutdown.pod b/crypto/openssl/doc/ssl/SSL_set_shutdown.pod index 6b196c1..6289e63 100644 --- a/crypto/openssl/doc/ssl/SSL_set_shutdown.pod +++ b/crypto/openssl/doc/ssl/SSL_set_shutdown.pod @@ -46,7 +46,10 @@ 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. +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)>). @@ -63,6 +66,7 @@ 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/crypto/openssl/doc/ssl/SSL_shutdown.pod b/crypto/openssl/doc/ssl/SSL_shutdown.pod index c4ae670..6b5012b 100644 --- a/crypto/openssl/doc/ssl/SSL_shutdown.pod +++ b/crypto/openssl/doc/ssl/SSL_shutdown.pod @@ -22,10 +22,52 @@ 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 behaviour of SSL_shutdown() depends on the underlying BIO. +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 the 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 has been finished or an error occurred. +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() @@ -38,6 +80,12 @@ 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: @@ -46,19 +94,23 @@ The following return values can occur: =item 1 -The shutdown was successfully completed. +The shutdown was successfully completed. The "close notify" alert was sent +and the peer's "close notify" alert was received. =item 0 -The shutdown was not successful. Call SSL_get_error() with the return -value B<ret> to find out the reason. +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 of +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 SSL_get_error() with the return value B<ret> to find out the reason. +Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret> +to find out the reason. =back @@ -66,6 +118,7 @@ Call SSL_get_error() with the return value B<ret> to find out the reason. 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)> diff --git a/crypto/openssl/doc/ssl/SSL_state_string.pod b/crypto/openssl/doc/ssl/SSL_state_string.pod new file mode 100644 index 0000000..4404595 --- /dev/null +++ b/crypto/openssl/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> + + char *SSL_state_string(SSL *ssl); + char *SSL_state_string_long(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/crypto/openssl/doc/ssl/SSL_want.pod b/crypto/openssl/doc/ssl/SSL_want.pod new file mode 100644 index 0000000..50cc89d --- /dev/null +++ b/crypto/openssl/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(SSL *ssl); + int SSL_want_nothing(SSL *ssl); + int SSL_want_read(SSL *ssl); + int SSL_want_write(SSL *ssl); + int SSL_want_x509_lookup(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/crypto/openssl/doc/ssl/SSL_write.pod b/crypto/openssl/doc/ssl/SSL_write.pod index b0dfefa..dfa42e9 100644 --- a/crypto/openssl/doc/ssl/SSL_write.pod +++ b/crypto/openssl/doc/ssl/SSL_write.pod @@ -25,11 +25,9 @@ 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 not the case if a generic -method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that +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() -must be used before the first call to an L<SSL_read(3)|SSL_read(3)> -or SSL_write() function. +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 @@ -80,8 +78,14 @@ bytes actually written to the TLS/SSL connection. =item 0 -The write operation was not successful. Call SSL_get_error() with the return -value B<ret> to find out, whether an error occurred. +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 diff --git a/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod index 9a1ba6c..0321a5a 100644 --- a/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod +++ b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod @@ -30,7 +30,17 @@ 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. +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 @@ -50,7 +60,7 @@ 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(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/crypto/openssl/doc/ssl/ssl.pod b/crypto/openssl/doc/ssl/ssl.pod index e521245..a1ff455 100644 --- a/crypto/openssl/doc/ssl/ssl.pod +++ b/crypto/openssl/doc/ssl/ssl.pod @@ -299,7 +299,7 @@ protocol context defined in the B<SSL_CTX> structure. =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)(SSL_CTX *), char *arg) +=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); @@ -650,8 +650,10 @@ 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)>, @@ -661,18 +663,28 @@ 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_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>, L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(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_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)>, @@ -685,12 +697,19 @@ 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_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(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_pending(3)|SSL_pending(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_write(3)|SSL_write(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)>, |
