From 7e55354aa4b06dead79c8a2c91756d71c0f02030 Mon Sep 17 00:00:00 2001 From: kris Date: Sun, 18 Feb 2001 03:17:36 +0000 Subject: Import of OpenSSL 0.9.6-STABLE snapshot dated 2001-02-10 --- crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod | 67 ++++- .../doc/ssl/SSL_CTX_add_extra_chain_cert.pod | 38 +++ crypto/openssl/doc/ssl/SSL_CTX_add_session.pod | 65 +++++ crypto/openssl/doc/ssl/SSL_CTX_flush_sessions.pod | 49 ++++ .../openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod | 53 ++++ crypto/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod | 50 ++++ .../doc/ssl/SSL_CTX_load_verify_locations.pod | 124 +++++++++ crypto/openssl/doc/ssl/SSL_CTX_new.pod | 9 +- .../doc/ssl/SSL_CTX_sess_set_cache_size.pod | 50 ++++ crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod | 81 ++++++ crypto/openssl/doc/ssl/SSL_CTX_sessions.pod | 34 +++ crypto/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod | 4 +- .../openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod | 90 +++++++ .../doc/ssl/SSL_CTX_set_default_passwd_cb.pod | 70 +++++ crypto/openssl/doc/ssl/SSL_CTX_set_options.pod | 183 +++++++++++++ .../doc/ssl/SSL_CTX_set_session_cache_mode.pod | 106 ++++++++ .../doc/ssl/SSL_CTX_set_session_id_context.pod | 82 ++++++ crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod | 55 ++++ crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod | 284 +++++++++++++++++++++ crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod | 154 +++++++++++ .../doc/ssl/SSL_SESSION_get_ex_new_index.pod | 61 +++++ crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod | 63 +++++ crypto/openssl/doc/ssl/SSL_accept.pod | 2 +- crypto/openssl/doc/ssl/SSL_clear.pod | 2 +- crypto/openssl/doc/ssl/SSL_connect.pod | 4 +- crypto/openssl/doc/ssl/SSL_get_client_CA_list.pod | 52 ++++ crypto/openssl/doc/ssl/SSL_get_error.pod | 30 ++- .../doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod | 61 +++++ crypto/openssl/doc/ssl/SSL_get_ex_new_index.pod | 59 +++++ crypto/openssl/doc/ssl/SSL_load_client_CA_file.pod | 62 +++++ crypto/openssl/doc/ssl/SSL_new.pod | 1 + crypto/openssl/doc/ssl/SSL_pending.pod | 13 + crypto/openssl/doc/ssl/SSL_read.pod | 2 +- crypto/openssl/doc/ssl/SSL_set_session.pod | 3 +- crypto/openssl/doc/ssl/SSL_write.pod | 8 +- crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod | 55 ++++ crypto/openssl/doc/ssl/ssl.pod | 139 ++++++---- 37 files changed, 2189 insertions(+), 76 deletions(-) create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_add_session.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_flush_sessions.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_sessions.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_options.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_timeout.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod create mode 100644 crypto/openssl/doc/ssl/SSL_CTX_use_certificate.pod create mode 100644 crypto/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod create mode 100644 crypto/openssl/doc/ssl/SSL_SESSION_get_time.pod create mode 100644 crypto/openssl/doc/ssl/SSL_get_client_CA_list.pod create mode 100644 crypto/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod create mode 100644 crypto/openssl/doc/ssl/SSL_get_ex_new_index.pod create mode 100644 crypto/openssl/doc/ssl/SSL_load_client_CA_file.pod create mode 100644 crypto/openssl/doc/ssl/d2i_SSL_SESSION.pod (limited to 'crypto/openssl/doc/ssl') 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, currently SSL_CIPHER_description() returns a textual description of the cipher used into the buffer B of length B provided. B must be at least -128 bytes, otherwise the string "Buffer too small" is returned. If B -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 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), 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 + +Textual representation of the cipher name. + +=item + +Protocol version: B, B. The TLSv1 ciphers are flagged with SSLv3. + +=item Kx= + +Key exchange method: B (for export ciphers as B or +B), B (for export ciphers as B or B), +B, B, B. + +=item Au= + +Authentication method: B, B, B, B. None is the +representation of anonymous ciphers. + +=item Enc= + +Encryption method with number of secret bits: B, B, +B<3DES(168)>, B, B, B, B, +B, B, B, B, B, B. + +=item Mac= + +Message digest: B, B. + +=item + +If the cipher is flagged exportable with respect to old US crypto +regulations, the word "B" 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 being NULL, the library crashes. +If SSL_CIPHER_description() cannot handle a built-in cipher, the according +description of the cipher property is B. This case should not +occur. + =head1 RETURN VALUES See DESCRIPTION @@ -52,6 +107,6 @@ See DESCRIPTION =head1 SEE ALSO L, L, -L +L, L =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 + + long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509) + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B 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. + +=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, +L, +L + +=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 + + 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 to the context B. The +reference count for session B is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L. + +SSL_CTX_remove_session() removes the session B from the context B. +L is called once for B. + +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, +L, +L + +=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 + + 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 to remove sessions expired at time B. + +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) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B 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). + +=head1 RETURN VALUES + +=head1 SEE ALSO + +L, +L, +L, +L + +=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 + + 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 for B +into the B object. + +SSL_CTX_get_ex_data() is used to retrieve the information for B from +B. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L. + +=head1 SEE ALSO + +L, +L, +L + +=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 + + 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. + +SSL_get_verify_mode() returns the verification mode currently set in +B. + +SSL_CTX_get_verify_depth() returns the verification depth limit currently set +in B. 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. 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. 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. 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, L + +=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 + + 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, at +which CA certificates for verification purposes are located. The certificates +available via B and B are trusted. + +=head1 NOTES + +If B 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 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 are listed to the client +as available CAs during the TLS/SSL handshake. + +If B 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 utility to create the necessary links. + +The certificates in B 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 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, then those in B. 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/B, if the +certificate chain was not explicitely specified (see +L, +L. + +=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: + + cd /some/where/certs + c_rehash . + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed because B and B 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, +L, +L, +L, +L + + +=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 + + 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 to B. + +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 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, +L, +L + +=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 + + 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/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 interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L). +The new_session_cb() is passed the B connection and the ssl session +B. 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 and the ssl session B. +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 connection, the session id of length B at the memory location +B. With the parameter B the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object. + +=head1 SEE ALSO + +L, L, +L, +L + +=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 + + 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. + +=head1 NOTES + +The sessions in the internal session cache are kept in an +L 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 operations, so that the database must not be +modified directly but by using the +L family of functions. + +=head1 SEE ALSO + +L, L, +L, +L + +=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, L, +L, L =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 + + 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 of CAs sent to the client when +requesting a client certificate for B. + +SSL_set_client_CA_list() sets the B of CAs sent to the client when +requesting a client certificate for the chosen B, overriding the +setting valid for B's SSL_CTX object. + +SSL_CTX_add_client_CA() adds the CA name extracted from B to the +list of CAs sent to the client when requesting a client certificate for +B. + +SSL_add_client_CA() adds the CA name extracted from B to the +list of CAs sent to the client when requesting a client certificate for +the chosen B, overriding the setting valid for B's SSL_CTX object. + +=head1 NOTES + +When a TLS/SSL server requests a client certificate (see +B), 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 option in +L +are sent. + +This list can be explicitely set using the SSL_CTX_set_client_CA_list() for +B and SSL_set_client_CA_list() for the specific B. The list +specified overrides the previous setting. The CAs listed do not become +trusted (B only contains the names, not the complete certificates); use +L +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 or B (as appropriate) is opened. The CAs implicitly +specified using +L +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. Check the error stack +to find out the reason. + +=back + +=head1 SEE ALSO + +L, +L, +L +L + +=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 + + 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 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 +is provided. The pem_passwd_cb must write the password into the provided buffer +B which is of size B. The actual length of the password must +be returned to the calling function. B 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 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 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, +L + +=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 + + 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 to B. +Options already set before are not cleared. + +SSL_set_options() adds the options set via bitmask in B to B. +Options already set before are not cleared. + +SSL_CTX_get_options() returns the options set for B. + +SSL_get_options() returns the options set for B. + +=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 +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 do not affect already created +SSL objects. SSL_clear() does not affect the settings. + +The following B 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 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. + +SSL_CTX_get_options() and SSL_get_options() return the current bitmask. + +=head1 SEE ALSO + +L, L, L + +=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 + + 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 to . + +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, 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). + +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 +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 function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and +L 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, L, +L, +L, +L, +L, +L + +=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 + + 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 of length +B within which a session can be reused for the B object. + +SSL_set_session_id_context() sets the context B of length +B within which a session can be reused for the B object. + +=head1 NOTES + +Sessions are generated within a certain context. When exporting/importing +sessions with B/B 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 which is used to distinguish +the contexts and is stored in exported sessions. The B 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 is limited to +B. + +=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 of the session id context B exceeded +the maximum allowed length of B. The error +is logged to the error stack. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L + +=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 + + 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 to B. The timeout value B must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B. + +=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 family of functions. + +Expired sessions are removed from the internal session cache, whenever +L is called, either +directly by the application or automatically (see +L) + +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, +L, +L, +L + +=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 + + 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 to be B and +specifies the B function to be used. If no callback function +shall be specified, the NULL pointer can be used for B. + +SSL_set_verify() sets the verification flags for B to be B and +specifies the B function to be used. If no callback function +shall be specified, the NULL pointer can be used for B. In +this case last B set specifically for this B remains. If +no special B was set before, the default callback for the underlying +B is used, that was valid at the the time B was created with +L. + +SSL_CTX_set_verify_depth() sets the maximum B for the certificate chain +verification that shall be allowed for B. (See the BUGS section.) + +SSL_set_verify_depth() sets the maximum B for the certificate chain +verification that shall be allowed for B. (See the BUGS section.) + +=head1 NOTES + +The verification of certificates can be controlled by a set of logically +or'ed B flags: + +=over 4 + +=item SSL_VERIFY_NONE + +B the server will not send a client certificate request to the +client, so the client will not send a certificate. + +B 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 function. +The handshake will be continued regardless of the verification result. + +=item SSL_VERIFY_PEER + +B 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, 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 the server certificate is verified. If the verification process +fails as indicated by B, 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 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 ignored + +=item SSL_VERIFY_CLIENT_ONCE + +B 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 ignored + +=back + +Exactly one of the B 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 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 indicates, whether the verification of +the certificate in question was passed (preverify_ok=1) or not +(preverify_ok=0). B 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 +and B is called with B=0. By applying +X509_CTX_store_* functions B can locate the certificate +in question and perform additional steps (see EXAMPLES). If no error is +found for a certificate, B is called with B=1 +before advancing to the next level. + +The return value of B controls the strategy of the further +verification process. If B 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 returns 1, +the verification process is continued. If B 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 or by maintaining its +own error storage managed by B. + +If no B is specified, the default callback will be used. +Its return value is identical to B, 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 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, +L). + + ... + 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, L, +L, +L, +L, +L, +L, +L + +=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 + + 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. The information is passed to SSL objects B +created from B with L by copying, so that +changes applied to B 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 is called for this SSL object. + +SSL_CTX_use_certificate() loads the certificate B into B, +SSL_use_certificate() loads B into B. The rest of the +certificates needed to form the complete certificate chain can be +specified using the +L +function. + +SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from +the memory location B (with length B) into B, +SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B. + +SSL_CTX_use_certificate_file() loads the first certificate stored in B +into B. The formatting B 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 into B. +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 into B. 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 as private key to B. +SSL_CTX_use_RSAPrivateKey() adds the private key B of type RSA +to B. SSL_use_PrivateKey() adds B as private key to B; +SSL_use_RSAPrivateKey() adds B as private key of type RSA to B. + +SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B +stored at memory location B (length B) to B. +SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA +stored at memory location B (length B) to B. +SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private +key to B. + +SSL_CTX_use_PrivateKey_file() adds the first private key found in +B to B. The formatting B 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 to B. SSL_use_PrivateKey_file() adds the first private key found +in B to B; SSL_use_RSAPrivateKey_file() adds the first private +RSA key found to B. + +SSL_CTX_check_private_key() checks the consistency of a private key with +the corresponding certificate loaded into B. 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. If no key/certificate was explicitly added for +this B, the last item added into B 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. + +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as B, 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. +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. + +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. +(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, L, L, +L, +L, +L, +L + +=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 + + 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 for B +into the B object. + +SSL_SESSION_get_ex_data() is used to retrieve the information for B from +B. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L. + +=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, +L, +L + +=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 + + 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 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 with +the chosen value B. + +SSL_SESSION_get_timeout() returns the timeout value set for session B +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B in seconds +to B. + +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. +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, +0 is returned. + +=head1 SEE ALSO + +L, +L + +=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 to find out the reason. -=item -1 +=item E0 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, L, -L +L, L =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 to find out the reason. -=item -1 +=item E0 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, L, -L, L , L +L, L, L =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 + + 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 using L. + +SSL_get_client_CA_list() returns the list of client CAs explicitely +set for B using SSL_set_client_CA_list() or B's SSL_CTX object with +L, 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 or in server mode) or send +by the server (client mode). + +=item NULL + +No client CA list was explicitely set (for B or in server mode) or +the server did not send a list of CAs (client mode). + +=back + +=head1 SEE ALSO + +L, +L + +=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. 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. The value returned by +that TLS/SSL I/O function must be passed to SSL_get_error() in parameter B. In addition to B and B, 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 has data available for reading (if the result code is -B) or allows writing data (B). -For socket Bs (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 has data +available for reading (if the result code is B) +or allows writing data (B), 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 or B 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 Bs (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 and B, i.e. SSL_read() -may want to write data and SSL_write() may want to read data. +B and B. 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 + + 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=0 + +The index value to access the pointer. + +=item E0 + +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, + +=head1 SEE ALSO + +L, L, +L + +=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 + + 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 for B into +the B object. + +SSL_get_ex_data() is used to retrieve the information for B from +B. + +A detailed description for the B<*_get_ex_new_index()> functionality +can be found in L. +The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in +L. + +=head1 EXAMPLES + +An example on how to use the functionality is included in the example +verify_callback() in L. + +=head1 SEE ALSO + +L, +L, +L, +L + +=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 + + STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); + +=head1 DESCRIPTION + +SSL_load_client_CA_file() reads certificates from B 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, +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, +L + +=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, L, +L, L =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. 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 object's +I 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, L =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 to find out, whether an error occurred. -=item -1 +=item E0 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, L +L, L, +L =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 or B. 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 to find out, whether an error occurred. -=item -1 +=item E0 -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 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 + + 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 with length B, into +an SSL_SESSION object. + +i2d_SSL_SESSION() transforms the SSL_SESSION object B into the ASN1 +representation and stores it into the memory location pointed to by B. +The length of the resulting ASN1 representation is returned. If B 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 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, 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, +L + +=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 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. + +Then an B object is created as a framework to establish +TLS/SSL enabled connections (see L). +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 object. After the B object has been created using +L, L or +L can be used to associate the network +connection with the object. + +Then the TLS/SSL handshake is performed using +L or L +respectively. +L and L are used +to read and write data on the TLS/SSL connection. +L can be used to shut down the +TLS/SSL connection. + +=head1 DATA STRUCTURES + +Currently the OpenSSL B library functions deals with the following data +structures: + +=over 4 + +=item B (SSL Method) + +That's a dispatch structure describing the internal B library +methods/functions which implement the various protocol versions (SSLv1, SSLv2 +and TLSv1). It's needed to create an B. + +=item B (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 basis and the actually used ones are then part of the +B. + +=item B (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 structures which are later created for the connections. + +=item B (SSL Session) + +This is a structure containing the current TLS/SSL session details for a +connection: Bs, client and server certificates, keys, etc. + +=item B (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 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 library functions deals with the following data -structures: - -=over 4 - -=item B (SSL Method) - -That's a dispatch structure describing the internal B library -methods/functions which implement the various protocol versions (SSLv1, SSLv2 -and TLSv1). It's needed to create an B. - -=item B (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 basis and the actually used ones are then part of the -B. - -=item B (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 structures which are later created for the connections. - -=item B (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: Bs, client and server certificates, keys, etc. - -=item B (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 library exports 214 API functions. @@ -625,20 +648,48 @@ connection defined in the B structure. L, L, L, L, -L, L, +L, +L, +L, +L, +L, +L, +L, +L +L, +L, +L, +L, +L, +L, +L, +L, +L, L, +L, +L, +L, L, -L, L, +L, +L, +L, +L, +L, L, L, L, L, -L, L, +L, +L, +L, L, L, L, L, L, L, L, -L +L, +L, +L, +L =head1 HISTORY -- cgit v1.1