diff options
Diffstat (limited to 'crypto/openssl/doc')
49 files changed, 1656 insertions, 90 deletions
diff --git a/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod index d352925..cea9002 100644 --- a/crypto/openssl/doc/apps/ca.pod +++ b/crypto/openssl/doc/apps/ca.pod @@ -54,6 +54,11 @@ The options descriptions will be divided into each purpose. specifies the configuration file to use. +=item B<-name section> + +specifies the configuration file section to use (overrides +B<default_ca> in the B<ca> section). + =item B<-in filename> an input filename containing a single certificate request to be @@ -202,8 +207,20 @@ that some software (for example Netscape) can't handle V2 CRLs. =head1 CONFIGURATION FILE OPTIONS -The options for B<ca> are contained in the B<ca> section of the -configuration file. Many of these are identical to command line +The section of the configuration file containing options for B<ca> +is found as follows: If the B<-name> command line option is used, +then it names the section to be used. Otherwise the section to +be used must be named in the B<default_ca> option of the B<ca> section +of the configuration file (or in the default section of the +configuration file). Besides B<default_ca>, the following options are +read directly from the B<ca> section: + RANDFILE + preserve + msie_hack +With the exception of B<RANDFILE>, this is probably a bug and may +change in future releases. + +Many of the configuration file options are identical to command line options. Where the option is present in the configuration file and the command line the command line value is used. Where an option is described as mandatory then it must be present in diff --git a/crypto/openssl/doc/apps/openssl.pod b/crypto/openssl/doc/apps/openssl.pod index 0cbd199..e3c79a4 100644 --- a/crypto/openssl/doc/apps/openssl.pod +++ b/crypto/openssl/doc/apps/openssl.pod @@ -125,6 +125,10 @@ Generation of RSA Parameters. Generation of hashed passwords. +=item L<B<pkcs12>|pkcs12(1)> + +PKCS#12 Data Management. + =item L<B<pkcs7>|pkcs7(1)> PKCS#7 Data Management. diff --git a/crypto/openssl/doc/apps/verify.pod b/crypto/openssl/doc/apps/verify.pod index 9045552..ea5c29c 100644 --- a/crypto/openssl/doc/apps/verify.pod +++ b/crypto/openssl/doc/apps/verify.pod @@ -200,13 +200,13 @@ the signature of the certificate is invalid. Unused. the certificate is not yet valid: the notBefore date is after the current time. -=item B<10 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> +=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> -the CRL is not yet valid. Unused. +the certificate has expired: that is the notAfter date is before the current time. -=item B<11 X509_V_ERR_CERT_HAS_EXPIRED: Certificate has expired> +=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> -the certificate has expired: that is the notAfter date is before the current time. +the CRL is not yet valid. Unused. =item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> diff --git a/crypto/openssl/doc/crypto/BN_rand.pod b/crypto/openssl/doc/crypto/BN_rand.pod index cbae2fc..ecd410f 100644 --- a/crypto/openssl/doc/crypto/BN_rand.pod +++ b/crypto/openssl/doc/crypto/BN_rand.pod @@ -14,6 +14,8 @@ BN_rand, BN_pseudo_rand - generate pseudo-random number int BN_rand_range(BIGNUM *rnd, BIGNUM *range); + int BN_pseudo_rand_range(BIGNUM *rnd, int bits, int top, int bottom); + =head1 DESCRIPTION BN_rand() generates a cryptographically strong pseudo-random number of @@ -31,6 +33,8 @@ protocols, but usually not for key generation etc. BN_rand_range() generates a cryptographically strong pseudo-random number B<rnd> in the range 0 <lt>= B<rnd> E<lt> B<range>. +BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(), +and hence numbers generated by it are not necessarily unpredictable. The PRNG must be seeded prior to calling BN_rand() or BN_rand_range(). @@ -49,5 +53,6 @@ L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)> BN_rand() is available in all versions of SSLeay and OpenSSL. BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case and the function BN_rand_range() were added in OpenSSL 0.9.6a. +BN_pseudo_rand_range() was added in OpenSSL 0.9.6c. =cut diff --git a/crypto/openssl/doc/crypto/bn.pod b/crypto/openssl/doc/crypto/bn.pod index d183028..1524bc2 100644 --- a/crypto/openssl/doc/crypto/bn.pod +++ b/crypto/openssl/doc/crypto/bn.pod @@ -61,6 +61,7 @@ bn - multiprecision integer arithmetics int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); int BN_rand_range(BIGNUM *rnd, BIGNUM *range); + int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); diff --git a/crypto/openssl/doc/crypto/threads.pod b/crypto/openssl/doc/crypto/threads.pod index bc7ff9b..136844b 100644 --- a/crypto/openssl/doc/crypto/threads.pod +++ b/crypto/openssl/doc/crypto/threads.pod @@ -53,8 +53,10 @@ OpenSSL can safely be used in multi-threaded applications provided that at least two callback functions are set. locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. Multi-threaded -applications will crash at random if it is not set. +needed to perform locking on shared data structures. +(Note that OpenSSL uses a number of global data structures that +will be implicitly shared whenever multiple threads use OpenSSL.) +Multi-threaded applications will crash at random if it is not set. locking_function() must be able to handle up to CRYPTO_num_locks() different mutex locks. It sets the B<n>-th lock if B<mode> & 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)>, diff --git a/crypto/openssl/doc/ssleay.txt b/crypto/openssl/doc/ssleay.txt index fab8d42..c6049d5 100644 --- a/crypto/openssl/doc/ssleay.txt +++ b/crypto/openssl/doc/ssleay.txt @@ -1,6 +1,22 @@ Bundle of old SSLeay documentation files [OBSOLETE!] +*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** + +OBSOLETE means that nothing in this document should be trusted. This +document is provided mostly for historical purposes (it wasn't even up +to date at the time SSLeay 0.8.1 was released) and as inspiration. If +you copy some snippet of code from this document, please _check_ that +it really is correct from all points of view. For example, you can +check with the other documents in this directory tree, or by comparing +with relevant parts of the include files. + +People have done the mistake of trusting what's written here. Please +don't do that. + +*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** + + ==== readme ======================================================== This is the old 0.6.6 docuementation. Most of the cipher stuff is still |
