Backport documentation added for 0.9.7.

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_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
-SSL_CIPHER_description - get SSL_CIPHER properties
 
 =head1 SYNOPSIS
 
@@ -29,9 +28,10 @@ SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently
 
 SSL_CIPHER_description() returns a textual description of the cipher used
 into the buffer B<buf> of length B<len> provided. B<len> must be at least
-128 bytes, otherwise the string "Buffer too small" is returned. If B<buf>
+128 bytes, otherwise a pointer to the the string "Buffer too small" is
-is NULL, a buffer of 128 bytes is allocated using OPENSSL_malloc(). If the
+returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using
-allocation fails, the string "OPENSSL_malloc Error" is returned.
+OPENSSL_malloc(). If the allocation fails, a pointer to the string
+"OPENSSL_malloc Error" is returned.
 
 =head1 NOTES
 
@@ -40,11 +40,66 @@ export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm
 does use the full 128 bits (which would be returned for B<alg_bits>), of
 which however 88bits are fixed. The search space is hence only 40 bits.
 
+The string returned by SSL_CIPHER_description() in case of success consists
+of cleartext information seperated by one or more blanks in the following
+sequence:
+
+=over 4
+
+=item <ciphername>
+
+Textual representation of the cipher name.
+
+=item <protocol version>
+
+Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3.
+
+=item Kx=<key exchange>
+
+Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or
+B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>),
+B<DH/RSA>, B<DH/DSS>, B<Fortezza>.
+
+=item Au=<authentication>
+
+Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the
+representation of anonymous ciphers.
+
+=item Enc=<symmectric encryption method>
+
+Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>,
+B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>,
+B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>.
+
+=item Mac=<message authentication code>
+
+Message digest: B<MD5>, B<SHA1>.
+
+=item <export flag>
+
+If the cipher is flagged exportable with respect to old US crypto
+regulations, the word "B<export>" is printed.
+
+=back
+
+=head1 EXAMPLES
+
+Some examples for the output of SSL_CIPHER_description():
+
+ EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
+ EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
+ RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5
+ EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
+
 =head1 BUGS
 
 If SSL_CIPHER_description() is called with B<cipher> being NULL, the
 library crashes.
 
+If SSL_CIPHER_description() cannot handle a built-in cipher, the according
+description of the cipher property is B<unknown>. This case should not
+occur.
+
 =head1 RETURN VALUES
 
 See DESCRIPTION
@@ -52,6 +107,6 @@ See DESCRIPTION
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>,
-L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>
+L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>
 
 =cut

doc/ssl/SSL_CTX_load_verify_locations.pod

@@ -40,15 +40,43 @@ as available CAs during the TLS/SSL handshake.
 If B<CApath> is not NULL, it points to a directory containing CA certificates
 in PEM format. The files each contain one CA certificate. The files are
 looked up by the CA subject name hash value, which must hence be available.
+If more than one CA certificate with the same name hash value exist, the
+extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
+is performed in the ordering of the extension number, regardless of other
+properties of the certificates.
 Use the B<c_rehash> utility to create the necessary links.
 
-The certificates in B<CAfile> are only looked up when required, e.g. when
+The certificates in B<CApath> are only looked up when required, e.g. when
 building the certificate chain or when actually performing the verification
 of a peer certificate.
 
 On a server, the certificates in B<CApath> are not listed as available
 CA certificates to a client during a TLS/SSL handshake.
 
+When looking up CA certificates, the OpenSSL library will first search the
+certificates in B<CAfile>, then those in B<CApath>. Certificate matching
+is done based on the subject name, the key identifier (if present), and the
+serial number as taken from the certificate to be verified. If these data
+do not match, the next certificate will be tried. If a first certificate
+matching the parameters is found, the verification process will be performed;
+no other certificates for the same parameters will be searched in case of
+failure.
+
+When building its own certificate chain, an OpenSSL client/server will
+try to fill in missing certificates from B<CAfile>/B<CApath>, if the
+certificate chain was not explicitely specified (see
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>.
+
+=head1 WARNINGS
+
+If several CA certificates matching the name, key identifier, and serial
+number condition are available, only the first one will be examined. This
+may lead to unexpected results if the same CA certificate is available
+with different expiration dates. If a "certificate expired" verification
+error occurs, no other certificate will be searched. Make sure to not
+have expired certificates mixed with valid ones.
+
 =head1 EXAMPLES
 
 Generate a CA certificate file with descriptive text from the CA certificates
@@ -88,6 +116,9 @@ The operation succeeded.
 
 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_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
+
 
 =cut

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
+SSLv3 protocol. A client will send out SSLv3 client hello messages
-and will indicate that it also understands TLSv1. A server will only understand
+and will indicate that it only understands SSLv3. A server will only understand
-SSLv3 and TLSv1 client hello messages. This especially means, that it will
+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)
 

doc/ssl/SSL_CTX_set_cipher_list.pod

@@ -2,8 +2,7 @@
 
 =head1 NAME
 
-SSL_CTX_set_cipher_list, SSL_set_cipher_list 
+SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
-- choose list of available SSL_CIPHERs
 
 =head1 SYNOPSIS
 
@@ -47,6 +46,7 @@ could be selected and 0 on complete failure.
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
 L<ciphers(1)|ciphers(1)>
 
 =cut

doc/ssl/SSL_connect.pod

@@ -51,7 +51,7 @@ The TLS/SSL handshake was not successful but was shut down controlled and
 by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
 return value B<ret> to find out the reason.
 
-=item -1
+=item E<lt>0
 
 The TLS/SSL handshake was not successful, because a fatal error occurred either
 at the protocol level or a connection failure occurred. The shutdown was
@@ -64,6 +64,6 @@ to find out the reason.
 =head1 SEE ALSO
 
 L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>,
-L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
 
 =cut

doc/ssl/SSL_write.pod

@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_read - write bytes to a TLS/SSL connection.
+SSL_write - write bytes to a TLS/SSL connection.
 
 =head1 SYNOPSIS
 
@@ -31,7 +31,7 @@ when the underlying BIO could not satisfy the needs of SSL_write()
 to continue the operation. In this case a call to SSL_get_error() with the
 return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
 B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
-call to SSL_write() can also cause write operations! The calling process
+call to SSL_write() can also cause read operations! The calling process
 then must repeat the call after taking appropriate action to satisfy the
 needs of SSL_write(). The action depends on the underlying BIO. When using a
 non-blocking socket, nothing is to be done, but select() can be used to check
@@ -62,7 +62,7 @@ value B<ret> to find out, whether an error occurred.
 
 =item E<lt>0
 
-The read operation was not successful, because either an error occurred
+The write operation was not successful, because either an error occurred
 or action must be taken by the calling process. Call SSL_get_error() with the
 return value B<ret> to find out the reason.
 

doc/ssl/ssl.pod

@@ -13,6 +13,69 @@ The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
 Transport Layer Security (TLS v1) protocols. It provides a rich API which is
 documented here.
 
+At first the library must be initialized; see
+L<SSL_library_init(3)|SSL_library_init(3)>.
+
+Then an B<SSL_CTX> object is created as a framework to establish
+TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>).
+Various options regarding certificates, algorithms etc. can be set
+in this object.
+
+When a network connection has been created, it can be assigned to an
+B<SSL> object. After the B<SSL> object has been created using
+L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or
+L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network
+connection with the object.
+
+Then the TLS/SSL handshake is performed using
+L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)>
+respectively.
+L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used
+to read and write data on the TLS/SSL connection.
+L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the
+TLS/SSL connection.
+
+=head1 DATA STRUCTURES
+
+Currently the OpenSSL B<ssl> library functions deals with the following data
+structures:
+
+=over 4
+
+=item B<SSL_METHOD> (SSL Method)
+
+That's a dispatch structure describing the internal B<ssl> library
+methods/functions which implement the various protocol versions (SSLv1, SSLv2
+and TLSv1). It's needed to create an B<SSL_CTX>.
+
+=item B<SSL_CIPHER> (SSL Cipher)
+
+This structure holds the algorithm information for a particular cipher which
+are a core part of the SSL/TLS protocol. The available ciphers are configured
+on a B<SSL_CTX> basis and the actually used ones are then part of the
+B<SSL_SESSION>.
+
+=item B<SSL_CTX> (SSL Context)
+
+That's the global context structure which is created by a server or client
+once per program life-time and which holds mainly default values for the
+B<SSL> structures which are later created for the connections.
+
+=item B<SSL_SESSION> (SSL Session)
+
+This is a structure containing the current TLS/SSL session details for a
+connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
+
+=item B<SSL> (SSL Connection)
+
+That's the main SSL/TLS structure which is created by a server or client per
+established connection. This actually is the core structure in the SSL API.
+Under run-time the application usually deals with this structure which has
+links to mostly all other structures.
+
+=back
+
+
 =head1 HEADER FILES
 
 Currently the OpenSSL B<ssl> library provides the following C header files
@@ -55,46 +118,6 @@ it's already included by ssl.h>.
 
 =back
 
-=head1 DATA STRUCTURES
-
-Currently the OpenSSL B<ssl> library functions deals with the following data
-structures:
-
-=over 4
-
-=item B<SSL_METHOD> (SSL Method)
-
-That's a dispatch structure describing the internal B<ssl> library
-methods/functions which implement the various protocol versions (SSLv1, SSLv2
-and TLSv1). It's needed to create an B<SSL_CTX>.
-
-=item B<SSL_CIPHER> (SSL Cipher)
-
-This structure holds the algorithm information for a particular cipher which
-are a core part of the SSL/TLS protocol. The available ciphers are configured
-on a B<SSL_CTX> basis and the actually used ones are then part of the
-B<SSL_SESSION>.
-
-=item B<SSL_CTX> (SSL Context)
-
-That's the global context structure which is created by a server or client
-once per program life-time and which holds mainly default values for the
-B<SSL> structures which are later created for the connections.
-
-=item B<SSL_SESSION> (SSL Session)
-
-This is a structure containing the current TLS/SSL session details for a
-connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
-
-=item B<SSL> (SSL Connection)
-
-That's the main SSL/TLS structure which is created by a server or client per
-established connection. This actually is the core structure in the SSL API.
-Under run-time the application usually deals with this structure which has
-links to mostly all other structures.
-
-=back
-
 =head1 API FUNCTIONS
 
 Currently the OpenSSL B<ssl> library exports 214 API functions.
@@ -626,13 +649,23 @@ connection defined in the B<SSL> structure.
 L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>,
 L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>,
 L<SSL_connect(3)|SSL_connect(3)>,
+L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_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_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
+L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
 L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>,
+L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
 L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
 L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
-L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(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)>,
@@ -644,7 +677,8 @@ L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
 L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>,
 L<SSL_set_session(3)|SSL_set_session(3)>,
 L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>,
-L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>
 
 =head1 HISTORY