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