From c032563a0a2377100d2b8ff44388a8f719d66eb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= Date: Sun, 28 Jan 2001 18:31:35 +0000 Subject: [PATCH] Backport documentation added for 0.9.7. --- doc/ssl/SSL_CIPHER_get_name.pod | 67 ++++++++++-- doc/ssl/SSL_CTX_load_verify_locations.pod | 35 ++++++- doc/ssl/SSL_CTX_new.pod | 9 +- doc/ssl/SSL_CTX_set_cipher_list.pod | 4 +- doc/ssl/SSL_connect.pod | 4 +- doc/ssl/SSL_write.pod | 6 +- doc/ssl/ssl.pod | 120 ++++++++++++++-------- 7 files changed, 183 insertions(+), 62 deletions(-) diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod index 7fea14ee68..bf851dcea5 100644 --- a/doc/ssl/SSL_CIPHER_get_name.pod +++ b/doc/ssl/SSL_CIPHER_get_name.pod @@ -2,8 +2,7 @@ =head1 NAME -SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, -SSL_CIPHER_description - get SSL_CIPHER properties +SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties =head1 SYNOPSIS @@ -29,9 +28,10 @@ SSL_CIPHER_get_version() returns the protocol version for B, currently SSL_CIPHER_description() returns a textual description of the cipher used into the buffer B of length B provided. B must be at least -128 bytes, otherwise the string "Buffer too small" is returned. If B -is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the -allocation fails, the string "OPENSSL_malloc Error" is returned. +128 bytes, otherwise a pointer to the the string "Buffer too small" is +returned. If B is NULL, a buffer of 128 bytes is allocated using +OPENSSL_malloc(). If the allocation fails, a pointer to the string +"OPENSSL_malloc Error" is returned. =head1 NOTES @@ -40,11 +40,66 @@ export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm does use the full 128 bits (which would be returned for B), of which however 88bits are fixed. The search space is hence only 40 bits. +The string returned by SSL_CIPHER_description() in case of success consists +of cleartext information seperated by one or more blanks in the following +sequence: + +=over 4 + +=item + +Textual representation of the cipher name. + +=item + +Protocol version: B, B. The TLSv1 ciphers are flagged with SSLv3. + +=item Kx= + +Key exchange method: B (for export ciphers as B or +B), B (for export ciphers as B or B), +B, B, B. + +=item Au= + +Authentication method: B, B, B, B. None is the +representation of anonymous ciphers. + +=item Enc= + +Encryption method with number of secret bits: B, B, +B<3DES(168)>, B, B, B, B, +B, B, B, B, B, B. + +=item Mac= + +Message digest: B, B. + +=item + +If the cipher is flagged exportable with respect to old US crypto +regulations, the word "B" is printed. + +=back + +=head1 EXAMPLES + +Some examples for the output of SSL_CIPHER_description(): + + EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 + EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 + RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 + EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export + =head1 BUGS If SSL_CIPHER_description() is called with B being NULL, the library crashes. +If SSL_CIPHER_description() cannot handle a built-in cipher, the according +description of the cipher property is B. This case should not +occur. + =head1 RETURN VALUES See DESCRIPTION @@ -52,6 +107,6 @@ See DESCRIPTION =head1 SEE ALSO L, L, -L +L, L =cut diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod index d46f8aab5f..0e2d2179c8 100644 --- a/doc/ssl/SSL_CTX_load_verify_locations.pod +++ b/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -40,15 +40,43 @@ as available CAs during the TLS/SSL handshake. If B is not NULL, it points to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. Use the B utility to create the necessary links. -The certificates in B are only looked up when required, e.g. when +The certificates in B are only looked up when required, e.g. when building the certificate chain or when actually performing the verification of a peer certificate. On a server, the certificates in B are not listed as available CA certificates to a client during a TLS/SSL handshake. +When looking up CA certificates, the OpenSSL library will first search the +certificates in B, then those in B. Certificate matching +is done based on the subject name, the key identifier (if present), and the +serial number as taken from the certificate to be verified. If these data +do not match, the next certificate will be tried. If a first certificate +matching the parameters is found, the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. + +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from B/B, if the +certificate chain was not explicitely specified (see +L, +L. + +=head1 WARNINGS + +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. + =head1 EXAMPLES Generate a CA certificate file with descriptive text from the CA certificates @@ -88,6 +116,9 @@ The operation succeeded. L, L, -L +L, +L, +L + =cut diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index e166c692c3..8b16ea3c90 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -33,9 +33,9 @@ understand SSLv2 client hello messages. =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) A TLS/SSL connection established with these methods will only understand the -SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages -and will indicate that it also understands TLSv1. A server will only understand -SSLv3 and TLSv1 client hello messages. This especially means, that it will +SSLv3 protocol. A client will send out SSLv3 client hello messages +and will indicate that it only understands SSLv3. A server will only understand +SSLv3 client hello messages. This especially means, that it will not understand SSLv2 client hello messages which are widely used for compatibility reasons, see SSLv23_*_method(). @@ -46,7 +46,8 @@ TLSv1 protocol. A client will send out TLSv1 client hello messages and will indicate that it only understands TLSv1. A server will only understand TLSv1 client hello messages. This especially means, that it will not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). +compatibility reasons, see SSLv23_*_method(). It will also not understand +SSLv3 client hello messages. =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod index 272d6b3de2..9a29eeeb95 100644 --- a/doc/ssl/SSL_CTX_set_cipher_list.pod +++ b/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -2,8 +2,7 @@ =head1 NAME -SSL_CTX_set_cipher_list, SSL_set_cipher_list -- choose list of available SSL_CIPHERs +SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs =head1 SYNOPSIS @@ -47,6 +46,7 @@ could be selected and 0 on complete failure. =head1 SEE ALSO L, L, +L, L =cut diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod index debe41744f..00813ecfff 100644 --- a/doc/ssl/SSL_connect.pod +++ b/doc/ssl/SSL_connect.pod @@ -51,7 +51,7 @@ The TLS/SSL handshake was not successful but was shut down controlled and by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the return value B to find out the reason. -=item -1 +=item E0 The TLS/SSL handshake was not successful, because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was @@ -64,6 +64,6 @@ to find out the reason. =head1 SEE ALSO L, L, -L, L , L +L, L, L =cut diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod index 7ce625ac21..8110161522 100644 --- a/doc/ssl/SSL_write.pod +++ b/doc/ssl/SSL_write.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_read - write bytes to a TLS/SSL connection. +SSL_write - write bytes to a TLS/SSL connection. =head1 SYNOPSIS @@ -31,7 +31,7 @@ when the underlying BIO could not satisfy the needs of SSL_write() to continue the operation. In this case a call to SSL_get_error() with the return value of SSL_write() will yield B or B. As at any time a re-negotiation is possible, a -call to SSL_write() can also cause write operations! The calling process +call to SSL_write() can also cause read operations! The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_write(). The action depends on the underlying BIO. When using a non-blocking socket, nothing is to be done, but select() can be used to check @@ -62,7 +62,7 @@ value B to find out, whether an error occurred. =item E0 -The read operation was not successful, because either an error occurred +The write operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value B to find out the reason. diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index a4a3959dc0..c0eb40031b 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -13,6 +13,69 @@ The OpenSSL B library implements the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. It provides a rich API which is documented here. +At first the library must be initialized; see +L. + +Then an B object is created as a framework to establish +TLS/SSL enabled connections (see L). +Various options regarding certificates, algorithms etc. can be set +in this object. + +When a network connection has been created, it can be assigned to an +B object. After the B object has been created using +L, L or +L can be used to associate the network +connection with the object. + +Then the TLS/SSL handshake is performed using +L or L +respectively. +L and L are used +to read and write data on the TLS/SSL connection. +L can be used to shut down the +TLS/SSL connection. + +=head1 DATA STRUCTURES + +Currently the OpenSSL B library functions deals with the following data +structures: + +=over 4 + +=item B (SSL Method) + +That's a dispatch structure describing the internal B library +methods/functions which implement the various protocol versions (SSLv1, SSLv2 +and TLSv1). It's needed to create an B. + +=item B (SSL Cipher) + +This structure holds the algorithm information for a particular cipher which +are a core part of the SSL/TLS protocol. The available ciphers are configured +on a B basis and the actually used ones are then part of the +B. + +=item B (SSL Context) + +That's the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +B structures which are later created for the connections. + +=item B (SSL Session) + +This is a structure containing the current TLS/SSL session details for a +connection: Bs, client and server certificates, keys, etc. + +=item B (SSL Connection) + +That's the main SSL/TLS structure which is created by a server or client per +established connection. This actually is the core structure in the SSL API. +Under run-time the application usually deals with this structure which has +links to mostly all other structures. + +=back + + =head1 HEADER FILES Currently the OpenSSL B library provides the following C header files @@ -55,46 +118,6 @@ it's already included by ssl.h>. =back -=head1 DATA STRUCTURES - -Currently the OpenSSL B library functions deals with the following data -structures: - -=over 4 - -=item B (SSL Method) - -That's a dispatch structure describing the internal B library -methods/functions which implement the various protocol versions (SSLv1, SSLv2 -and TLSv1). It's needed to create an B. - -=item B (SSL Cipher) - -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a B basis and the actually used ones are then part of the -B. - -=item B (SSL Context) - -That's the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -B structures which are later created for the connections. - -=item B (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: Bs, client and server certificates, keys, etc. - -=item B (SSL Connection) - -That's the main SSL/TLS structure which is created by a server or client per -established connection. This actually is the core structure in the SSL API. -Under run-time the application usually deals with this structure which has -links to mostly all other structures. - -=back - =head1 API FUNCTIONS Currently the OpenSSL B library exports 214 API functions. @@ -626,13 +649,23 @@ connection defined in the B structure. L, L, L, L, L, +L, +L, +L, +L, L L, -L +L, +L, L, +L, +L, L, L, -L, L, +L, +L, +L, +L, L, L, L, @@ -644,7 +677,8 @@ L, L, L, L, L, L, L, -L +L, +L =head1 HISTORY