diff options
| author | kris <kris@FreeBSD.org> | 2001-02-18 03:17:36 +0000 |
|---|---|---|
| committer | kris <kris@FreeBSD.org> | 2001-02-18 03:17:36 +0000 |
| commit | 7e55354aa4b06dead79c8a2c91756d71c0f02030 (patch) | |
| tree | 5058ee297163944bfec8dbad8c8cad174f437d82 /crypto/openssl/doc/ssl | |
| parent | 539b977eff7c71f628cb2a407543a51070b14763 (diff) | |
| download | FreeBSD-src-7e55354aa4b06dead79c8a2c91756d71c0f02030.zip FreeBSD-src-7e55354aa4b06dead79c8a2c91756d71c0f02030.tar.gz | |
Import of OpenSSL 0.9.6-STABLE snapshot dated 2001-02-10
Diffstat (limited to 'crypto/openssl/doc/ssl')
37 files changed, 2189 insertions, 76 deletions
diff --git a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod index 7fea14e..bf851dc 100644 --- a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod +++ b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod @@ -2,8 +2,7 @@ =head1 NAME -SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, -SSL_CIPHER_description - get SSL_CIPHER properties +SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties =head1 SYNOPSIS @@ -29,9 +28,10 @@ SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently SSL_CIPHER_description() returns a textual description of the cipher used into the buffer B<buf> of length B<len> provided. B<len> must be at least -128 bytes, otherwise the string "Buffer too small" is returned. If B<buf> -is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the -allocation fails, the string "OPENSSL_malloc Error" is returned. +128 bytes, otherwise a pointer to the the string "Buffer too small" is +returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using +OPENSSL_malloc(). If the allocation fails, a pointer to the string +"OPENSSL_malloc Error" is returned. =head1 NOTES @@ -40,11 +40,66 @@ export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm does use the full 128 bits (which would be returned for B<alg_bits>), of which however 88bits are fixed. The search space is hence only 40 bits. +The string returned by SSL_CIPHER_description() in case of success consists +of cleartext information seperated by one or more blanks in the following +sequence: + +=over 4 + +=item <ciphername> + +Textual representation of the cipher name. + +=item <protocol version> + +Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3. + +=item Kx=<key exchange> + +Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or +B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>), +B<DH/RSA>, B<DH/DSS>, B<Fortezza>. + +=item Au=<authentication> + +Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the +representation of anonymous ciphers. + +=item Enc=<symmectric encryption method> + +Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>, +B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>, +B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>. + +=item Mac=<message authentication code> + +Message digest: B<MD5>, B<SHA1>. + +=item <export flag> + +If the cipher is flagged exportable with respect to old US crypto +regulations, the word "B<export>" is printed. + +=back + +=head1 EXAMPLES + +Some examples for the output of SSL_CIPHER_description(): + + EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 + EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 + RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 + EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export + =head1 BUGS If SSL_CIPHER_description() is called with B<cipher> being NULL, the library crashes. +If SSL_CIPHER_description() cannot handle a built-in cipher, the according +description of the cipher property is B<unknown>. This case should not +occur. + =head1 RETURN VALUES See DESCRIPTION @@ -52,6 +107,6 @@ See DESCRIPTION =head1 SEE ALSO L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, -L<SSL_get_ciphers(3)|SSL_get_ciphers(3)> +L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod new file mode 100644 index 0000000..21a9db0 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_CTX_add_extra_chain_cert - add certificate to chain + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509) + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate +chain presented together with the certificate. Several certificates +can be added one after the other. + +=head1 NOTES + +When constructing the certificate chain, the chain will be formed from +these certificates explicitly specified. If no chain is specified, +the library will try to complete the chain from the available CA +certificates in the trusted CA storage, see +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. + +=head1 RETURN VALUES + +SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the +error stack to find out the reason for failure otherwise. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 0000000..af326c2 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); + + int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + +=head1 DESCRIPTION + +SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The +reference count for session B<c> is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. + +SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> is called once for B<c>. + +SSL_add_session() and SSL_remove_session() are synonyms for their +SSL_CTX_*() counterparts. + +=head1 NOTES + +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. In this case +it is assumed that both sessions are identical. If the same session is +stored in a different SSL_SESSION object, The old session is +removed and replaced by the new session. If the session is actually +identical (the SSL_SESSION object is identical), SSL_CTX_add_session() +is a no-op, and the return value is 0. + + +=head1 RETURN VALUES + +The following values are returned by all functions: + +=over 4 + +=item 0 + + The operation failed. In case of the add operation, it was tried to add + the same (identical) session twice. In case of the remove operation, the + session was not found in the cache. + +=item 1 + + The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_flush_sessions.pod b/crypto/openssl/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 0000000..148c36c --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); + void SSL_flush_sessions(SSL_CTX *ctx, long tm); + +=head1 DESCRIPTION + +SSL_CTX_flush_sessions() causes a run through the session cache of +B<ctx> to remove sessions expired at time B<tm>. + +SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). + +=head1 NOTES + +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see SSL_CTX_sess_set_cache_size()). +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. This can either be done + automatically whenever 255 new sessions were established (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B<tm> specifies the time which should be used for the +expiration test, in most cases the actual time given by time(0) +will be used. + +SSL_CTX_flush_sessions() will only check sessions stored in the internal +cache. When a session is found and removed, the remove_session_cb is however +called to synchronize with the external cache (see +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). + +=head1 RETURN VALUES + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod b/crypto/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod new file mode 100644 index 0000000..1506743 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); + + void *SSL_CTX_get_ex_data(SSL_CTX *ctx, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_CTX_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx> +into the B<ctx> object. + +SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from +B<ctx>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod b/crypto/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod new file mode 100644 index 0000000..7f10c6e --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_get_verify_mode(SSL_CTX *ctx); + int SSL_get_verify_mode(SSL *ssl); + int SSL_CTX_get_verify_depth(SSL_CTX *ctx); + int SSL_get_verify_depth(SSL *ssl); + int (*SSL_CTX_get_verify_callback(SSL_CTX *ctx))(int, X509_STORE_CTX *); + int (*SSL_get_verify_callback(SSL *ssl))(int, X509_STORE_CTX *); + +=head1 DESCRIPTION + +SSL_CTX_get_verify_mode() returns the verification mode currently set in +B<ctx>. + +SSL_get_verify_mode() returns the verification mode currently set in +B<ssl>. + +SSL_CTX_get_verify_depth() returns the verification depth limit currently set +in B<ctx>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_get_verify_depth() returns the verification depth limit currently set +in B<ssl>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_CTX_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ctx>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +SSL_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ssl>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000..0e2d217 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +SSL_CTX_load_verify_locations - set default locations for trusted CA +certificates + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, + const char *CApath); + +=head1 DESCRIPTION + +SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at +which CA certificates for verification purposes are located. The certificates +available via B<CAfile> and B<CApath> are trusted. + +=head1 NOTES + +If B<CAfile> is not NULL, it points to a file of CA certificates in PEM +format. The file can contain several CA certificates identified by + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + +sequences. Before, between, and after the certificates text is allowed +which can be used e.g. for descriptions of the certificates. + +The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() +function. + +If on an TLS/SSL server no special setting is perfomed using *client_CA_list() +functions, the certificates contained in B<CAfile> are listed to the client +as available CAs during the TLS/SSL handshake. + +If B<CApath> is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain one CA certificate. The files are +looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. +Use the B<c_rehash> utility to create the necessary links. + +The certificates in B<CApath> are only looked up when required, e.g. when +building the certificate chain or when actually performing the verification +of a peer certificate. + +On a server, the certificates in B<CApath> are not listed as available +CA certificates to a client during a TLS/SSL handshake. + +When looking up CA certificates, the OpenSSL library will first search the +certificates in B<CAfile>, then those in B<CApath>. Certificate matching +is done based on the subject name, the key identifier (if present), and the +serial number as taken from the certificate to be verified. If these data +do not match, the next certificate will be tried. If a first certificate +matching the parameters is found, the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. + +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from B<CAfile>/B<CApath>, if the +certificate chain was not explicitely specified (see +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>. + +=head1 WARNINGS + +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. + +=head1 EXAMPLES + +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: + + #!/bin/sh + rm CAfile.pem + for i in ca1.pem ca2.pem ca3.pem ; do + openssl x509 -in $i -text >> CAfile.pem + done + +Prepare the directory /some/where/certs containing several CA certificates +for use as B<CApath>: + + cd /some/where/certs + c_rehash . + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed because B<CAfile> and B<CApath> are NULL or the +processing at one of the locations specified failed. Check the error +stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> + + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_new.pod b/crypto/openssl/doc/ssl/SSL_CTX_new.pod index e166c69..8b16ea3 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_new.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_new.pod @@ -33,9 +33,9 @@ understand SSLv2 client hello messages. =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) A TLS/SSL connection established with these methods will only understand the -SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages -and will indicate that it also understands TLSv1. A server will only understand -SSLv3 and TLSv1 client hello messages. This especially means, that it will +SSLv3 protocol. A client will send out SSLv3 client hello messages +and will indicate that it only understands SSLv3. A server will only understand +SSLv3 client hello messages. This especially means, that it will not understand SSLv2 client hello messages which are widely used for compatibility reasons, see SSLv23_*_method(). @@ -46,7 +46,8 @@ TLSv1 protocol. A client will send out TLSv1 client hello messages and will indicate that it only understands TLSv1. A server will only understand TLSv1 client hello messages. This especially means, that it will not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). +compatibility reasons, see SSLv23_*_method(). It will also not understand +SSLv3 client hello messages. =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) diff --git a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 0000000..469933b --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); + long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_cache_size() sets the size of the internal session cache +of context B<ctx> to B<t>. + +SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. + +=head1 NOTES + +The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, +currently 1024*20, so that up to 20000 sessions can be held. This size +can be modified using the SSL_CTX_sess_set_cache_size() call. A special +case is the size 0, which is used for unlimited size. + +When the maximum number of sessions is reached, no more new sessions are +added to the cache. New space may be added by calling +L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> to remove +expired sessions. + +If the size of the session cache is reduced and more sessions are already +in the session cache, old session will be removed at the next time a +session shall be added. This removal is not synchronized with the +expiration of sessions. + +=head1 RETURN VALUES + +SSL_CTX_sess_set_cache_size() returns the previously valid size. + +SSL_CTX_sess_get_cache_size() returns the currently valid size. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> + +=cut 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 new file mode 100644 index 0000000..b6f15b4 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, + int (*new_session_cb)(SSL *, SSL_SESSION *)); + void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, + void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); + void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, + SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); + + int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); + void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); + + int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); + void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, + int len, int *copy); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically +called whenever a new session was negotiated. + +SSL_CTX_sess_set_remove_cb() sets the callback function, which is +automatically called whenever a session is removed by the SSL engine, +because it is considered faulty or the session has become obsolete because +of exceeding the timeout value. + +SSL_CTX_sess_set_get_cb() sets the callback function which is called, +whenever a SSL/TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +(SSL/TLS server only.) + +SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and +SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the +provided callback functions. If a callback function has not been set, +the NULL pointer is returned. + +=head1 NOTES + +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. Inside these callback +functions, session can be saved to disk or put into a database using the +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>). +The new_session_cb() is passed the B<ssl> connection and the ssl session +B<sess>. If the callback returns B<0>, the session will be immediately +removed again. + +The remove_session_cb() is called, whenever the SSL engine removes a session +from the internal cache. This happens if the session is removed because +it is expired or when a connection was not shutdown cleanly. The +remove_session_cb() is passed the B<ctx> and the ssl session B<sess>. +It does not provide any feedback. + +The get_session_cb() is only called on SSL/TLS servers with the session id +proposed by the client. The get_session_cb() is always called, also when +session caching was disabled. The get_session_cb() is passed the +B<ssl> connection, the session id of length B<length> at the memory location +B<data>. With the parameter B<copy> the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object. + +=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)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_sessions.pod b/crypto/openssl/doc/ssl/SSL_CTX_sessions.pod new file mode 100644 index 0000000..ad92a8c --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_sessions.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +SSL_CTX_sessions - access internal session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sessions() returns a pointer to the lhash databases containing the +internal session cache for B<ctx>. + +=head1 NOTES + +The sessions in the internal session cache are kept in an +L<lhash(3)|lhash(3)> type database. It is possible to directly +access this database e.g. for searching. In parallel, the sessions +form a linked list which is maintained seperatly from the +L<lhash(3)|lhash(3)> operations, so that the database must not be +modified directly but by using the +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>, +L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod index 272d6b3..9a29eee 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -2,8 +2,7 @@ =head1 NAME -SSL_CTX_set_cipher_list, SSL_set_cipher_list -- choose list of available SSL_CIPHERs +SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs =head1 SYNOPSIS @@ -47,6 +46,7 @@ could be selected and 0 on complete failure. =head1 SEE ALSO L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, L<ciphers(1)|ciphers(1)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 0000000..f27a291 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, +SSL_add_client_CA - set list of CAs sent to the client when requesting a +client certificate + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); + void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); + int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); + int SSL_add_client_CA(SSL *ssl, X509 *cacert); + +=head1 DESCRIPTION + +SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for B<ctx>. + +SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for the chosen B<ssl>, overriding the +setting valid for B<ssl>'s SSL_CTX object. + +SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +B<ctx>. + +SSL_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. + +=head1 NOTES + +When a TLS/SSL server requests a client certificate (see +B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which +it will accept certificates, to the client. If no special list is provided, +the CAs available using the B<CAfile> option in +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +are sent. + +This list can be explicitely set using the SSL_CTX_set_client_CA_list() for +B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list +specified overrides the previous setting. The CAs listed do not become +trusted (B<list> only contains the names, not the complete certificates); use +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +to additionally load them for verification. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional +items the list of client CAs. If no list was specified before using +SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client +CA list for B<ctx> or B<ssl> (as appropriate) is opened. The CAs implicitly +specified using +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +are no longer used automatically. + +These functions are only useful for TLS/SSL servers. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item 1 + +The operation succeeded. + +=item 0 + +A failure while manipulating the STACK_OF(X509_NAME) object occured or +the X509_NAME could not be extracted from B<cacert>. Check the error stack +to find out the reason. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)> +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod new file mode 100644 index 0000000..a5343a1 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); + void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); + + int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata); + +=head1 DESCRIPTION + +SSL_CTX_set_default_passwd_cb() sets the default password callback called +when loading/storing a PEM certificate with encryption. + +SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which +will be provided to the password callback on invocation. + +The pem_passwd_cb(), which must be provided by the application, hands back the +password to be used during decryption. On invocation a pointer to B<userdata> +is provided. The pem_passwd_cb must write the password into the provided buffer +B<buf> which is of size B<size>. The actual length of the password must +be returned to the calling function. B<rwflag> indicates whether the +callback is used for reading/decryption (rwflag=0) or writing/encryption +(rwflag=1). + +=head1 NOTES + +When loading or storing private keys, a password might be supplied to +protect the private key. The way this password can be supplied may depend +on the application. If only one private key is handled, it can be practical +to have pem_passwd_cb() handle the password dialog interactively. If several +keys have to be handled, it can be practical to ask for the password once, +then keep it in memory and use it several times. In the last case, the +password could be stored into the B<userdata> storage and the +pem_passwd_cb() only returns the password already stored. + +Other items in PEM formatting (certificates) can also be encrypted, it is +however not usual, as certificate information is considered public. + +=head1 RETURN VALUES + +SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata() +do not provide diagnostic information. + +=head1 EXAMPLES + +The following example returns the password provided as B<userdata> to the +calling function. The password is considered to be a '\0' terminated +string. If the password does not fit into the buffer, the password is +truncated. + + int pem_passwd_cb(char *buf, int size, int rwflag, void *password) + { + strncpy(buf, (char *)(password), size); + buf[size - 1] = '\0'; + return(strlen(buf)); + } + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod new file mode 100644 index 0000000..bd5b0cb --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -0,0 +1,183 @@ +=pod + +=head1 NAME + +SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_options(SSL_CTX *ctx, long options); + long SSL_set_options(SSL *ssl, long options); + + long SSL_CTX_get_options(SSL_CTX *ctx); + long SSL_get_options(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. +Options already set before are not cleared. + +SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. +Options already set before are not cleared. + +SSL_CTX_get_options() returns the options set for B<ctx>. + +SSL_get_options() returns the options set for B<ssl>. + +=head1 NOTES + +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bitmasks and can be combined by a logical B<or> +operation (|). Options can only be added but can never be reset. + +During a handshake, the option settings of the SSL object used. When +a new SSL object is created from a context using SSL_new(), the current +option setting is copied. Changes to B<ctx> do not affect already created +SSL objects. SSL_clear() does not affect the settings. + +The following B<bug workaround> options are available: + +=over 4 + +=item SSL_OP_MICROSOFT_SESS_ID_BUG + +www.microsoft.com - when talking SSLv2, if session-id reuse is +performed, the session-id passed back in the server-finished message +is different from the one decided upon. + +=item SSL_OP_NETSCAPE_CHALLENGE_BUG + +Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte +challenge but then appears to only use 16 bytes when generating the +encryption keys. Using 16 bytes is ok but it should be ok to use 32. +According to the SSLv3 spec, one should use 32 bytes for the challenge +when opperating in SSLv2/v3 compatablity mode, but as mentioned above, +this breaks this server so 16 bytes is the way to go. + +=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG + +ssl3.netscape.com:443, first a connection is established with RC4-MD5. +If it is then resumed, we end up using DES-CBC3-SHA. It should be +RC4-MD5 according to 7.6.1.3, 'cipher_suite'. + +Netscape-Enterprise/2.01 (https://merchant.netscape.com) has this bug. +It only really shows up when connecting via SSLv2/v3 then reconnecting +via SSLv3. The cipher list changes.... + +NEW INFORMATION. Try connecting with a cipher list of just +DES-CBC-SHA:RC4-MD5. For some weird reason, each new connection uses +RC4-MD5, but a re-connect tries to use DES-CBC-SHA. So netscape, when +doing a re-connect, always takes the first cipher in the cipher list. + +=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG + +... + +=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER + +... + +=item SSL_OP_MSIE_SSLV2_RSA_PADDING + +... + +=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG + +... + +=item SSL_OP_TLS_D5_BUG + +... + +=item SSL_OP_TLS_BLOCK_PADDING_BUG + +... + +=item SSL_OP_TLS_ROLLBACK_BUG + +Disable version rollback attack detection. + +During the client key exchange, the client must send the same information +about acceptable SSL/TLS protocol levels as during the first hello. Some +clients violate this rule by adapting to the server's answer. (Example: +the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server +only understands up to SSLv3. In this case the client must still use the +same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect +to the server's answer and violate the version rollback protection.) + +=item SSL_OP_ALL + +All of the above bug workarounds. + +=back + +It is save and recommended to use SSL_OP_ALL to enable the bug workaround +options. + +The following B<modifying> options are available: + +=over 4 + +=item SSL_OP_SINGLE_DH_USE + +Always create a new key when using temporary DH parameters. + +=item SSL_OP_EPHEMERAL_RSA + +Also use the temporary RSA key when doing RSA operations. + +=item SSL_OP_PKCS1_CHECK_1 + +... + +=item SSL_OP_PKCS1_CHECK_2 + +... + +=item SSL_OP_NETSCAPE_CA_DN_BUG + +If we accept a netscape connection, demand a client cert, have a +non-self-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 + +... + +=item SSL_OP_NO_SSLv2 + +Do not use the SSLv2 protocol. + +=item SSL_OP_NO_SSLv3 + +Do not use the SSLv3 protocol. + +=item SSL_OP_NO_TLSv1 + +Do not use the TLSv1 protocol. + +=back + +=head1 RETURN VALUES + +SSL_CTX_set_options() and SSL_set_options() return the new options bitmask +after adding B<options>. + +SSL_CTX_get_options() and SSL_get_options() return the current bitmask. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)> + +=head1 HISTORY + +SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6. + +=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 new file mode 100644 index 0000000..ba3502a --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); + long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_session_cache_mode() enables/disables session caching +by setting the operational mode for B<ctx> to <mode>. + +SSL_CTX_get_session_cache_mode() returns the currently used cache mode. + +=head1 NOTES + +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each B<ctx>, if more than one +SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX +object. + +In order to reuse a session, a client must send the session's id to the +server. It can only send exactly one id. The server then decides whether it +agrees in reusing the session or starts the handshake for a new session. + +A server will lookup up the session in its internal session storage. If +the session is not found in internal storage or internal storage is +deactivated, the server will try the external storage if available. + +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>). + +The following session cache modes and modifiers are available: + +=over 4 + +=item SSL_SESS_CACHE_OFF + +No session caching for client or server takes place. + +=item SSL_SESS_CACHE_CLIENT + +Client sessions are added to the session cache. As there is no reliable way +for the OpenSSL library to know whether a session should be reused or which +session to choose (due to the abstract BIO layer the SSL engine does not +have details about the connection), the application must select the session +to be reused by using the L<SSL_set_session(3)|SSL_set_session(3)> +function. This option is not activated by default. + +=item SSL_SESS_CACHE_SERVER + +Server sessions are added to the session cache. When a client proposes a +session to be reused, the session is looked up in the internal session cache. +If the session is found, the server will try to reuse the session. +This is the default. + +=item SSL_SESS_CACHE_BOTH + +Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. + +=item SSL_SESS_CACHE_NO_AUTO_CLEAR + +Normally the session cache is checked for expired sessions every +255 connections using the +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> can be called +explicitly by the application. + +=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP + +By setting this flag sessions are cached in the internal storage but +they are not looked up automatically. If an external session cache +is enabled, sessions are looked up in the external cache. As automatic +lookup only applies for SSL/TLS servers, the flag has no effect on +clients. + +=back + +The default mode is SSL_SESS_CACHE_SERVER. + +=head1 RETURN VALUES + +SSL_CTX_set_session_cache_mode() returns the previously set cache mode. + +SSL_CTX_get_session_cache_mode() returns the currently set cache mode. + + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, +L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, +L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_timeout.pod(3)|SSL_CTX_set_timeout.pod(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod new file mode 100644 index 0000000..5949395 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ctx> object. + +SSL_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ssl> object. + +=head1 NOTES + +Sessions are generated within a certain context. When exporting/importing +sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, +to re-import a session generated from another context (e.g. another +application), which might lead to malfunctions. Therefore each application +must set its own session id context B<sid_ctx> which is used to distinguish +the contexts and is stored in exported sessions. The B<sid_ctx> can be +any kind of binary data with a given length, it is therefore possible +to use e.g. the name of the application and/or the hostname and/or service +name ... + +The session id context becomes part of the session. The session id context +is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and +SSL_set_session_id_context() functions are therefore only useful on the +server side. + +OpenSSL clients will check the session id context returned by the server +when reusing a session. + +The maximum length of the B<sid_ctx> is limited to +B<SSL_MAX_SSL_SESSION_ID_LENGTH>. + +=head1 WARNINGS + +If the session id context is not set on an SSL/TLS server, stored sessions +will not be reused but a fatal error will be flagged and the handshake +will fail. + +If a server returns a different session id context to an OpenSSL client +when reusing a session, an error will be flagged and the handshake will +fail. OpenSSL servers will always return the correct session id context, +as an OpenSSL server checks the session id context itself before reusing +a session as described above. + +=head1 RETURN VALUES + +SSL_CTX_set_session_id_context() and SSL_set_session_id_context() +return the following values: + +=over 4 + +=item 0 + +The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded +the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error +is logged to the error stack. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 0000000..21faed1 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); + long SSL_CTX_get_timeout(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_timeout() sets the timeout for newly created sessions for +B<ctx> to B<t>. The timeout value B<t> must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. + +=head1 NOTES + +Whenever a new session is created, it is assigned a maximum lifetime. This +lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. If the actual time is later than creation +time plus timeout, the session is not reused. + +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. Changes of the timeout value +do not affect already established sessions. + +The expiration time of a single session can be modified using the +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)> family of functions. + +Expired sessions are removed from the internal session cache, whenever +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either +directly by the application or automatically (see +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>) + +The default value for session timeout is 300 seconds. + +=head1 RETURN VALUES + +SSL_CTX_set_timeout() returns the previously set timeout value. + +SSL_CTX_get_timeout() returns the currently set timeout value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod new file mode 100644 index 0000000..fc0b761 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod @@ -0,0 +1,284 @@ +=pod + +=head1 NAME + +SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, + int (*verify_callback)(int, X509_STORE_CTX *)); + void SSL_set_verify(SSL *s, int mode, + int (*verify_callback)(int, X509_STORE_CTX *)); + void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); + void SSL_set_verify_depth(SSL *s, int depth); + + int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. + +SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. In +this case last B<verify_callback> set specifically for this B<ssl> remains. If +no special B<callback> was set before, the default callback for the underlying +B<ctx> is used, that was valid at the the time B<ssl> was created with +L<SSL_new(3)|SSL_new(3)>. + +SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ctx>. (See the BUGS section.) + +SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ssl>. (See the BUGS section.) + +=head1 NOTES + +The verification of certificates can be controlled by a set of logically +or'ed B<mode> flags: + +=over 4 + +=item SSL_VERIFY_NONE + +B<Server mode:> the server will not send a client certificate request to the +client, so the client will not send a certificate. + +B<Client mode:> if not using an anonymous cipher (by default disabled), the +server will send a certificate which will be checked. The result of the +certificate verification process can be checked after the TLS/SSL handshake +using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function. +The handshake will be continued regardless of the verification result. + +=item SSL_VERIFY_PEER + +B<Server mode:> the server sends a client certificate request to the client. +The certificate returned (if any) is checked. If the verification process +fails as indicated by B<verify_callback>, 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 +immediately terminated with an alert message containing the reason for +the verification failure. If no server certificate is sent, because an +anonymous cipher is used, SSL_VERIFY_PEER is ignored. + +=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT + +B<Server mode:> if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a "handshake failure" alert. +This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=item SSL_VERIFY_CLIENT_ONCE + +B<Server mode:> only request a client certificate on the initial TLS/SSL +handshake. Do not ask for a client certificate again in case of a +renegotiation. This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=back + +Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be +set at any time. + +SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up +to which depth certificates in a chain are used during the verification +procedure. If the certificate chain is longer than allowed, the certificates +above the limit are ignored. Error messages are generated as if these +certificates would not be present, most likely a +X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. +The depth count is "level 0:peer certificate", "level 1: CA certificate", +"level 2: higher level CA certificate", and so on. Setting the maximum +depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9, +allowing for the peer certificate and additional 9 CA certificates. + +The B<verify_callback> function is used to control the behaviour when the +SSL_VERIFY_PEER flag is set. It must be supplied by the application and +receives two arguments: B<preverify_ok> indicates, whether the verification of +the certificate in question was passed (preverify_ok=1) or not +(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used +for the certificate chain verification. + +The certificate chain is checked starting with the deepest nesting level +(the root CA certificate) and worked upward to the peer's certificate. +At each level signatures and issuer attributes are checked. Whenever +a verification error is found, the error number is stored in B<x509_ctx> +and B<verify_callback> is called with B<preverify_ok>=0. By applying +X509_CTX_store_* functions B<verify_callback> can locate the certificate +in question and perform additional steps (see EXAMPLES). If no error is +found for a certificate, B<verify_callback> is called with B<preverify_ok>=1 +before advancing to the next level. + +The return value of B<verify_callback> controls the strategy of the further +verification process. If B<verify_callback> returns 0, the verification +process is immediately stopped with "verification failed" state. If +SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and +the TLS/SSL handshake is terminated. If B<verify_callback> returns 1, +the verification process is continued. If B<verify_callback> always returns +1, the TLS/SSL handshake will never be terminated because of this application +experiencing a verification failure. The calling process can however +retrieve the error code of the last verification error using +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its +own error storage managed by B<verify_callback>. + +If no B<verify_callback> is specified, the default callback will be used. +Its return value is identical to B<preverify_ok>, so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if SSL_VERIFY_PEER is set. + +=head1 BUGS + +In client mode, it is not checked whether the SSL_VERIFY_PEER flag +is set, but whether SSL_VERIFY_NONE is not set. This can lead to +unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not +used as required (exactly one must be set at any time). + +The certificate verification depth set with SSL[_CTX]_verify_depth() +stops the verification at a certain depth. The error message produced +will be that of an incomplete certificate chain and not +X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. + +=head1 RETURN VALUES + +The SSL*_set_verify*() functions do not provide diagnostic information. + +=head1 EXAMPLES + +The following code sequence realizes an example B<verify_callback> function +that will always continue the TLS/SSL handshake regardless of verification +failure, if wished. The callback realizes a verification depth limit with +more informational output. + +All verification errors are printed, informations about the certificate chain +are printed on request. +The example is realized for a server that does allow but not require client +certificates. + +The example makes use of the ex_data technique to store application data +into/retrieve application data from the SSL structure +(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). + + ... + typedef struct { + int verbose_mode; + int verify_depth; + int always_continue; + } mydata_t; + int mydata_index; + ... + static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) + { + char buf[256]; + X509 *err_cert; + int err, depth; + SSL *ssl; + mydata_t *mydata; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + /* + * Retrieve the pointer to the SSL of the connection currently treated + * and the application specific data stored into the SSL object. + */ + ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); + mydata = SSL_get_ex_data(ssl, mydata_index); + + X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); + + /* + * Catch a too long certificate chain. The depth limit set using + * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so + * that whenever the "depth>verify_depth" condition is met, we + * have violated the limit and want to log this error condition. + * We must do it here, because the CHAIN_TOO_LONG error would not + * be found explicitly; only errors introduced by cutting off the + * additional certificates would be logged. + */ + if (depth > mydata->verify_depth) { + preverify_ok = 0; + err = X509_V_ERR_CERT_CHAIN_TOO_LONG; + X509_STORE_CTX_set_error(ctx, err); + } + if (!preverify_ok) { + printf("verify error:num=%d:%s:depth=%d:%s\n", err, + X509_verify_cert_error_string(err), depth, buf); + } + else if (mydata->verbose_mode) + { + printf("depth=%d:%s\n", depth, buf); + } + + /* + * At this point, err contains the last verification error. We can use + * it for something special + */ + if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT) + { + X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); + printf("issuer= %s\n", buf); + } + + if (mydata->always_continue) + return 1; + else + return preverify_ok; + } + ... + + mydata_t mydata; + + ... + mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); + + ... + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, + verify_callback); + + /* + * Let the verify_callback catch the verify_depth error so that we get + * an appropriate error in the logfile. + */ + SSL_CTX_set_verify_depth(verify_depth + 1); + + /* + * Set up the SSL specific data into "mydata" and store it into th SSL + * structure. + */ + mydata.verify_depth = verify_depth; ... + SSL_set_ex_data(ssl, mydata_index, &mydata); + + ... + SSL_accept(ssl); /* check of success left out for clarity */ + if (peer = SSL_get_peer_certificate(ssl)) + { + if (SSL_get_verify_result(ssl) == X509_V_OK) + { + /* The client sent a certificate which verified OK */ + } + } + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, +L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, +L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod b/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod new file mode 100644 index 0000000..58fa3e6 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod @@ -0,0 +1,154 @@ +=pod + +=head1 NAME + +SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); + int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); + int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_certificate(SSL *ssl, X509 *x); + int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); + int SSL_use_certificate_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); + + int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); + int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, + long len); + int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); + int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); + int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); + int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len); + int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); + int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); + int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); + int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_check_private_key(SSL_CTX *ctx); + int SSL_check_private_key(SSL *ssl); + +=head1 DESCRIPTION + +These functions load the certificates and private keys into the SSL_CTX +or SSL object, respectively. + +The SSL_CTX_* class of functions loads the certificates and keys into the +SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> +created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that +changes applied to B<ctx> do not propagate to already existing SSL objects. + +The SSL_* class of functions only loads certificates and keys into a +specific SSL object. The specific information is kept, when +L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object. + +SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>, +SSL_use_certificate() loads B<x> into B<ssl>. The rest of the +certificates needed to form the complete certificate chain can be +specified using the +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> +function. + +SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from +the memory location B<d> (with length B<len>) into B<ctx>, +SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. + +SSL_CTX_use_certificate_file() loads the first certificate stored in B<file> +into B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. +See the NOTES section on why SSL_CTX_use_certificate_chain_file() +should be preferred. + +SSL_CTX_use_certificate_chain_file() loads a certificate chain from +B<file> into B<ctx>. The certificates must be in PEM format and must +be sorted starting with the certificate to the highest level (root CA). +There is no corresponding function working on a single SSL object. + +SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. +SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA +to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; +SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. + +SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk> +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private +key to B<ssl>. + +SSL_CTX_use_PrivateKey_file() adds the first private key found in +B<file> to B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in +B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found +in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private +RSA key found to B<ssl>. + +SSL_CTX_check_private_key() checks the consistency of a private key with +the corresponding certificate loaded into B<ctx>. If more than one +key/certificate pair (RSA/DSA) is installed, the last item installed will +be checked. If e.g. the last item was a RSA certificate or key, the RSA +key/certificate pair will be checked. SSL_check_private_key() performs +the same check for B<ssl>. If no key/certificate was explicitly added for +this B<ssl>, the last item added into B<ctx> will be checked. + +=head1 NOTES + +The internal certificate store of OpenSSL can hold two private key/certificate +pairs at a time: one key/certificate of type RSA and one key/certificate +of type DSA. The certificate used depends on the cipher select, see +also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>. + +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain +one certificate or private key, consequently +SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. +Files of type SSL_FILETYPE_PEM can contain more than one item. + +SSL_CTX_use_certificate_chain_file() adds the first certificate found +in the file to the certificate store. The other certificates are added +to the store of chain certificates using +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>. +There exists only one extra chain store, so that the same chain is appended +to both types of certificates, RSA and DSA! If it is not intented to use +both type of certificate at the same time, it is recommended to use the +SSL_CTX_use_certificate_chain_file() instead of the +SSL_CTX_use_certificate_file() function in order to allow the use of +complete certificate chains even when no trusted CA storage is used or +when the CA issuing the certificate shall not be added to the trusted +CA storage. + +If additional certificates are needed to complete the chain during the +TLS negotiation, CA certificates are additionally looked up in the +locations of trusted CA certificates, see +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. + +The private keys loaded from file can be encrypted. In order to successfully +load encrypted keys, a function returning the passphrase must have been +supplied, see +L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>. +(Certificate files might be encrypted as well from the technical point +of view, it however does not make sense as the data in the certificate +is considered public anyway.) + +=head1 RETURN VALUES + +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, +L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/crypto/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod new file mode 100644 index 0000000..dd5cb4f --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); + + void *SSL_SESSION_get_ex_data(SSL_SESSION *session, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_SESSION_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx> +into the B<session> object. + +SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from +B<session>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 WARNINGS + +The application data is only maintained for sessions held in memory. The +application data is not included when dumping the session with +i2d_SSL_SESSION() (and all functions indirectly calling the dump functions +like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can +therefore not be restored. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod b/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 0000000..cd33b73 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_get_timeout - retrieve and manipulate session time and timeout settings + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_SESSION_get_time(SSL_SESSION *s); + long SSL_SESSION_set_time(SSL_SESSION *s, long tm); + long SSL_SESSION_get_timeout(SSL_SESSION *s); + long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); + + long SSL_get_time(SSL_SESSION *s); + long SSL_set_time(SSL_SESSION *s, long tm); + long SSL_get_timeout(SSL_SESSION *s); + long SSL_set_timeout(SSL_SESSION *s, long tm); + +=head1 DESCRIPTION + +SSL_SESSION_get_time() returns the time at which the session B<s> was +established. The time is given in seconds since the Epoch and therefore +compatible to the time delivered by the time() call. + +SSL_SESSION_set_time() replaces the creation time of the session B<s> with +the chosen value B<tm>. + +SSL_SESSION_get_timeout() returns the timeout value set for session B<s> +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds +to B<tm>. + +The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() +functions are synonyms for the SSL_SESSION_*() counterparts. + +=head1 NOTES + +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the +default timeout value at creation, respectively, as set by +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>. +Using these functions it is possible to extend or shorten the lifetime +of the session. + +=head1 RETURN VALUES + +SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently +valid values. + +SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. + +If any of the function is passed the NULL pointer for the session B<s>, +0 is returned. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod index 0c79ac5..46f95ab 100644 --- a/crypto/openssl/doc/ssl/SSL_accept.pod +++ b/crypto/openssl/doc/ssl/SSL_accept.pod @@ -54,7 +54,7 @@ The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B<ret> to find out the reason. -=item -1 +=item E<lt>0 The TLS/SSL handshake was not successful because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was diff --git a/crypto/openssl/doc/ssl/SSL_clear.pod b/crypto/openssl/doc/ssl/SSL_clear.pod index 862fd82..aeb0b5c 100644 --- a/crypto/openssl/doc/ssl/SSL_clear.pod +++ b/crypto/openssl/doc/ssl/SSL_clear.pod @@ -34,6 +34,6 @@ The SSL_clear() operation was successful. =back L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>, -L<ssl(3)|ssl(3)> +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod index debe417..00813ec 100644 --- a/crypto/openssl/doc/ssl/SSL_connect.pod +++ b/crypto/openssl/doc/ssl/SSL_connect.pod @@ -51,7 +51,7 @@ The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B<ret> to find out the reason. -=item -1 +=item E<lt>0 The TLS/SSL handshake was not successful, because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was @@ -64,6 +64,6 @@ to find out the reason. =head1 SEE ALSO L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> +L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_get_client_CA_list.pod b/crypto/openssl/doc/ssl/SSL_get_client_CA_list.pod new file mode 100644 index 0000000..d358bc3 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_get_client_CA_list.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_get_client_CA_list(SSL *s); + STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_get_client_CA_list() returns the list of client CAs explicitely set for +B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>. + +SSL_get_client_CA_list() returns the list of client CAs explicitely +set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, when in +server mode. In client mode, SSL_get_client_CA_list returns the list of +client CAs sent from the server, if any. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item STACK_OF(X509_NAMES) + +List of CA names explicitely set (for B<ctx> or in server mode) or send +by the server (client mode). + +=item NULL + +No client CA list was explicitely set (for B<ctx> or in server mode) or +the server did not send a list of CAs (client mode). + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_error.pod b/crypto/openssl/doc/ssl/SSL_get_error.pod index d85b564..fefaf61 100644 --- a/crypto/openssl/doc/ssl/SSL_get_error.pod +++ b/crypto/openssl/doc/ssl/SSL_get_error.pod @@ -14,8 +14,8 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation SSL_get_error() returns a result code (suitable for the C "switch" statement) for a preceding call to SSL_connect(), SSL_accept(), -SSL_read(), or SSL_write() on B<ssl>. The value returned by that -TLS/SSL I/O function must be passed to SSL_get_error() in parameter +SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by +that TLS/SSL I/O function must be passed to SSL_get_error() in parameter B<ret>. In addition to B<ssl> and B<ret>, SSL_get_error() inspects the @@ -48,16 +48,26 @@ has been closed. =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE The operation did not complete; the same TLS/SSL I/O function should be -called again later. There will be protocol progress if, by then, the -underlying B<BIO> has data available for reading (if the result code is -B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>). -For socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that -select() or poll() on the underlying socket can be used to find out -when the TLS/SSL I/O function should be retried. +called again later. If, by then, the underlying B<BIO> has data +available for reading (if the result code is B<SSL_ERROR_WANT_READ>) +or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL +protocol progress will take place, i.e. at least part of an TLS/SSL +record will be read or written. Note that the retry may again lead to +a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition. +There is no fixed upper limit for the number of iterations that +may be necessary until progress becomes visible at application +protocol level. + +For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or +poll() on the underlying socket can be used to find out when the +TLS/SSL I/O function should be retried. Caveat: Any TLS/SSL I/O function can lead to either of -B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read() -may want to write data and SSL_write() may want to read data. +B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular, +SSL_read() or SSL_peek() may want to write data and SSL_write() may want +to read data. This is mainly because TLS/SSL handshakes may occur at any +time during the protocol (initiated by either the client or the server); +SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. =item SSL_ERROR_WANT_X509_LOOKUP diff --git a/crypto/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/crypto/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod new file mode 100644 index 0000000..165c6a5 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure +from X509_STORE_CTX + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_ex_data_X509_STORE_CTX_idx(void); + +=head1 DESCRIPTION + +SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which +the pointer to the SSL object is stored into the X509_STORE_CTX object. + +=head1 NOTES + +Whenever a X509_STORE_CTX object is created for the verification of the +peers certificate during a handshake, a pointer to the SSL object is +stored into the X509_STORE_CTX object to identify the connection affected. +To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can +be used with the correct index. This index is globally the same for all +X509_STORE_CTX objects and can be retrieved using +SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when +SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application +program directly or indirectly during other SSL setup functions or during +the handshake. + +The value depends on other index values defined for X509_STORE_CTX objects +before the SSL index is created. + +=head1 RETURN VALUES + +=over 4 + +=item E<gt>=0 + +The index value to access the pointer. + +=item E<lt>0 + +An error occurred, check the error stack for a detailed error message. + +=back + +=head1 EXAMPLES + +The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to +access the SSL object for the connection to be accessed during the +verify_callback() when checking the peers certificate. Please check +the example in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_ex_new_index.pod b/crypto/openssl/doc/ssl/SSL_get_ex_new_index.pod new file mode 100644 index 0000000..2b69bb1 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_get_ex_new_index.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int SSL_set_ex_data(SSL *ssl, int idx, void *arg); + + void *SSL_get_ex_data(SSL *ssl, int idx); + + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. + +SSL_get_ex_new_index() is used to register a new index for application +specific data. + +SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into +the B<ssl> object. + +SSL_get_ex_data() is used to retrieve the information for B<idx> from +B<ssl>. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L<RSA_get_ex_new_index.pod(3)|RSA_get_ex_new_index.pod(3)>. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. + +=head1 EXAMPLES + +An example on how to use the functionality is included in the example +verify_callback() in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, +L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>, +L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_load_client_CA_file.pod b/crypto/openssl/doc/ssl/SSL_load_client_CA_file.pod new file mode 100644 index 0000000..02527dc --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_load_client_CA_file.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_load_client_CA_file - load certificate names from file + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); + +=head1 DESCRIPTION + +SSL_load_client_CA_file() reads certificates from B<file> and returns +a STACK_OF(X509_NAME) with the subject names found. + +=head1 NOTES + +SSL_load_client_CA_file() reads a file of PEM formatted certificates and +extracts the X509_NAMES of the certificates found. While the name suggests +the specific usage as support function for +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +it is not limited to CA certificates. + +=head1 EXAMPLES + +Load names of CAs from file and use it as a client CA list: + + SSL_CTX *ctx; + STACK_OF(X509_NAME) *cert_names; + + ... + cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); + if (cert_names != NULL) + SSL_CTX_set_client_CA_list(ctx, cert_names); + else + error_handling(); + ... + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The operation failed, check out the error stack for the reason. + +=item Pointer to STACK_OF(X509_NAME) + +Pointer to the subject names of the successfully read certificates. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_new.pod b/crypto/openssl/doc/ssl/SSL_new.pod index 8e8638f..3b084e8 100644 --- a/crypto/openssl/doc/ssl/SSL_new.pod +++ b/crypto/openssl/doc/ssl/SSL_new.pod @@ -37,6 +37,7 @@ The return value points to an allocated SSL structure. =head1 SEE ALSO L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_pending.pod b/crypto/openssl/doc/ssl/SSL_pending.pod index 744e185..b4c4859 100644 --- a/crypto/openssl/doc/ssl/SSL_pending.pod +++ b/crypto/openssl/doc/ssl/SSL_pending.pod @@ -25,6 +25,19 @@ L<SSL_read(3)|SSL_read(3)>. The number of bytes pending is returned. +=head1 BUGS + +SSL_pending() takes into account only bytes from the TLS/SSL record +that is currently being processed (if any). If the B<SSL> object's +I<read_ahead> flag is set, additional protocol bytes may have been +read containing more TLS/SSL records; these are ignored by +SSL_pending(). + +Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type +of pending data is application data. + +=head1 SEE ALSO + L<SSL_read(3)|SSL_read(3)>, L<ssl(3)|ssl(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_read.pod b/crypto/openssl/doc/ssl/SSL_read.pod index 072dc26..9bff325 100644 --- a/crypto/openssl/doc/ssl/SSL_read.pod +++ b/crypto/openssl/doc/ssl/SSL_read.pod @@ -61,7 +61,7 @@ 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. -=item -1 +=item E<lt>0 The read operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the diff --git a/crypto/openssl/doc/ssl/SSL_set_session.pod b/crypto/openssl/doc/ssl/SSL_set_session.pod index 9f78d9e..c4f7878 100644 --- a/crypto/openssl/doc/ssl/SSL_set_session.pod +++ b/crypto/openssl/doc/ssl/SSL_set_session.pod @@ -40,6 +40,7 @@ The operation succeeded. =head1 SEE ALSO -L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> +L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(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_write.pod b/crypto/openssl/doc/ssl/SSL_write.pod index db67c18..8110161 100644 --- a/crypto/openssl/doc/ssl/SSL_write.pod +++ b/crypto/openssl/doc/ssl/SSL_write.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_read - write bytes to a TLS/SSL connection. +SSL_write - write bytes to a TLS/SSL connection. =head1 SYNOPSIS @@ -31,7 +31,7 @@ when the underlying BIO could not satisfy the needs of SSL_write() to continue the operation. In this case a call to SSL_get_error() with the return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a -call to SSL_write() can also cause write operations! The calling process +call to SSL_write() can also cause read operations! The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_write(). The action depends on the underlying BIO. When using a non-blocking socket, nothing is to be done, but select() can be used to check @@ -60,9 +60,9 @@ bytes actually written to the TLS/SSL connection. The write operation was not successful. Call SSL_get_error() with the return value B<ret> to find out, whether an error occurred. -=item -1 +=item E<lt>0 -The read operation was not successful, because either an error occurred +The write operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value B<ret> to find out the reason. diff --git a/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod new file mode 100644 index 0000000..8142b6b --- /dev/null +++ b/crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME +d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, unsigned char **pp, long length); + int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); + +=head1 DESCRIPTION + +d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS +session, stored as binary data at location B<pp> with length B<length>, into +an SSL_SESSION object. + +i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 +representation and stores it into the memory location pointed to by B<pp>. +The length of the resulting ASN1 representation is returned. If B<pp> is +the NULL pointer, only the length is calculated and returned. + +=head1 NOTES + +The SSL_SESSION object is built from several malloc()ed parts, it can +therefore not be moved, copied or stored directly. In order to store +session data on disk or into a database, it must be transformed into +a binary ASN1 representation. + +When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically +allocated. + +When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be +large enough to hold the binary representation of the session. There is no +known limit on the size of the created ASN1 representation, so the necessary +amount of space should be obtained by first calling i2d_SSL_SESSION() with +B<pp=NULL>, and obtain the size needed, then allocate the memory and +call i2d_SSL_SESSION() again. + +=head1 RETURN VALUES + +d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION +object. In case of failure the NULL-pointer is returned and the error message +can be retrieved from the error stack. + +i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. +When the session is not valid, B<0> is returned and no operation is performed. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_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 8ffe590..2911c83 100644 --- a/crypto/openssl/doc/ssl/ssl.pod +++ b/crypto/openssl/doc/ssl/ssl.pod @@ -13,6 +13,69 @@ The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. It provides a rich API which is documented here. +At first the library must be initialized; see +L<SSL_library_init(3)|SSL_library_init(3)>. + +Then an B<SSL_CTX> object is created as a framework to establish +TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>). +Various options regarding certificates, algorithms etc. can be set +in this object. + +When a network connection has been created, it can be assigned to an +B<SSL> object. After the B<SSL> object has been created using +L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or +L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network +connection with the object. + +Then the TLS/SSL handshake is performed using +L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)> +respectively. +L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used +to read and write data on the TLS/SSL connection. +L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the +TLS/SSL connection. + +=head1 DATA STRUCTURES + +Currently the OpenSSL B<ssl> library functions deals with the following data +structures: + +=over 4 + +=item B<SSL_METHOD> (SSL Method) + +That's a dispatch structure describing the internal B<ssl> library +methods/functions which implement the various protocol versions (SSLv1, SSLv2 +and TLSv1). It's needed to create an B<SSL_CTX>. + +=item B<SSL_CIPHER> (SSL Cipher) + +This structure holds the algorithm information for a particular cipher which +are a core part of the SSL/TLS protocol. The available ciphers are configured +on a B<SSL_CTX> basis and the actually used ones are then part of the +B<SSL_SESSION>. + +=item B<SSL_CTX> (SSL Context) + +That's the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +B<SSL> structures which are later created for the connections. + +=item B<SSL_SESSION> (SSL Session) + +This is a structure containing the current TLS/SSL session details for a +connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. + +=item B<SSL> (SSL Connection) + +That's the main SSL/TLS structure which is created by a server or client per +established connection. This actually is the core structure in the SSL API. +Under run-time the application usually deals with this structure which has +links to mostly all other structures. + +=back + + =head1 HEADER FILES Currently the OpenSSL B<ssl> library provides the following C header files @@ -55,46 +118,6 @@ it's already included by ssl.h>. =back -=head1 DATA STRUCTURES - -Currently the OpenSSL B<ssl> library functions deals with the following data -structures: - -=over 4 - -=item B<SSL_METHOD> (SSL Method) - -That's a dispatch structure describing the internal B<ssl> library -methods/functions which implement the various protocol versions (SSLv1, SSLv2 -and TLSv1). It's needed to create an B<SSL_CTX>. - -=item B<SSL_CIPHER> (SSL Cipher) - -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a B<SSL_CTX> basis and the actually used ones are then part of the -B<SSL_SESSION>. - -=item B<SSL_CTX> (SSL Context) - -That's the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -B<SSL> structures which are later created for the connections. - -=item B<SSL_SESSION> (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. - -=item B<SSL> (SSL Connection) - -That's the main SSL/TLS structure which is created by a server or client per -established connection. This actually is the core structure in the SSL API. -Under run-time the application usually deals with this structure which has -links to mostly all other structures. - -=back - =head1 API FUNCTIONS Currently the OpenSSL B<ssl> library exports 214 API functions. @@ -625,20 +648,48 @@ connection defined in the B<SSL> structure. 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_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(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_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, +L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, +L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, +L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> +L<SSL_CTX_new(3)|SSL_CTX_new(3)>, +L<SSL_CTX_sess_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_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_options(3)|SSL_CTX_set_options(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_verify(3)|SSL_CTX_set_verify(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_get_error(3)|SSL_get_error(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, +L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, L<SSL_get_rbio(3)|SSL_get_rbio(3)>, L<SSL_get_session(3)|SSL_get_session(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_library_init(3)|SSL_library_init(3)>, L<SSL_new(3)|SSL_new(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_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> +L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, +L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, +L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, +L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> =head1 HISTORY |
