OpenSSL 0.9.7 stable 2002 05 08 merge

50 files changed, 2088 insertions, 98 deletions

diff --git a/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod b/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod
new file mode 100644
index 00000000000..2a987391147
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod
@@ -0,0 +1,70 @@
+=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 1
+
+The operation succeeded.
+
+=item 0
+
+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/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
index 21a9db0e2a4..ee28f5ccc3a 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
@@ -33,6 +33,7 @@ error stack to find out the reason for failure otherwise.
 
 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/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod b/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod
new file mode 100644
index 00000000000..fb6adcf50c1
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod
@@ -0,0 +1,34 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_free.pod b/lib/libssl/src/doc/ssl/SSL_CTX_free.pod
index c716cde164c..55e592f5f82 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_free.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_free.pod
@@ -24,6 +24,8 @@ the certificates and keys.
 
 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)>
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod b/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod
index 0f63537e784..84a799fc71d 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod
@@ -58,7 +58,7 @@ 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
-explicitely be set using the
+explicitly be set using the
 L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
 family of functions.
 
@@ -118,7 +118,7 @@ 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_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/lib/libssl/src/doc/ssl/SSL_CTX_new.pod b/lib/libssl/src/doc/ssl/SSL_CTX_new.pod
index 1dae8b0bdd0..465220a75c0 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_new.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_new.pod
@@ -59,10 +59,6 @@ choice when compatibility is a concern.
 
 =back
 
-If a generic method is used, it is necessary to explicitly set client or
-server mode with L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
-or SSL_set_accept_state().
-
 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
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod
index b6f15b44042..6e0ef00632a 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod
@@ -70,12 +70,16 @@ 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.
+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_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod
new file mode 100644
index 00000000000..81286ee650f
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod
@@ -0,0 +1,57 @@
+=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(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 X505_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/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod
new file mode 100644
index 00000000000..c0f4f857085
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod
@@ -0,0 +1,75 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod
index 9a29eeeb955..ed64f641570 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -34,9 +34,25 @@ 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, the respective is valid for DSA ciphers. Ciphers using EDH need
-a certificate and key and DH-parameters.
+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
 
@@ -47,6 +63,8 @@ could be selected and 0 on complete failure.
 
 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/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod
new file mode 100644
index 00000000000..53e18277138
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod
@@ -0,0 +1,90 @@
+=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.
+When B<client_cert_cb()> is NULL, not 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 the default
+certificate will be sent. A fatal error can be indicated by returning
+a negative value, in which case the handshake will be canceled.
+
+=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 no callback function is set, an OpenSSL client will send the certificate
+that was set using the
+L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions.
+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.
+The callback function can obtain the list of acceptable CAs using the
+L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)> function.
+
+If a callback function is defined, 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 SSL_use_certificate() and SSL_use_private_key() functions.
+Thus it will permanently override the certificate and key previously
+installed and will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>.
+If the callback returns no certificate, the OpenSSL library will send
+the certificate previously installed for the SSL_CTX object or the specific
+certificate of the SSL object, if available.
+
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
index a5343a1cf39..2b87f01ca15 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
@@ -40,6 +40,12 @@ 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.
 
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod
new file mode 100644
index 00000000000..798e8443a71
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod
@@ -0,0 +1,150 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod
new file mode 100644
index 00000000000..63d0b8d33f8
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod
@@ -0,0 +1,153 @@
+=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(SSL_CTX *ctx))();
+
+ void SSL_set_info_callback(SSL *ssl, void (*callback)());
+ void (*SSL_get_info_callback(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/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod
new file mode 100644
index 00000000000..da68cb9fc24
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod
@@ -0,0 +1,77 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod
index 9a035bb4d18..9822544e5e2 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod
@@ -37,6 +37,9 @@ The following mode changes are available:
 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
 
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod
new file mode 100644
index 00000000000..a423932d0af
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod
@@ -0,0 +1,97 @@
+=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().
+
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod
index 3dc7cc74ad6..c10055c6e7a 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod
@@ -17,10 +17,10 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man
 =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.
+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.
+Options already set before are not cleared!
 
 SSL_CTX_get_options() returns the options set for B<ctx>.
 
@@ -32,7 +32,12 @@ The behaviour of the SSL library can be changed by setting several options.
 The options are coded as bitmasks and can be combined by a logical B<or>
 operation (|). Options can only be added but can never be reset.
 
-During a handshake, the option settings of the SSL object used. When
+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_modes(3)|SSL_CTX_set_modes(3)> and SSL_set_modes() 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.
@@ -95,38 +100,62 @@ doing a re-connect, always takes the first cipher in the cipher list.
 
 ...
 
-=item SSL_OP_TLS_ROLLBACK_BUG
-
-Disable version rollback attack detection.
-
-During the client key exchange, the client must send the same information
-about acceptable SSL/TLS protocol levels as during the first hello. Some
-clients violate this rule by adapting to the server's answer. (Example:
-the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
-only understands up to SSLv3. In this case the client must still use the
-same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
-to the server's answer and violate the version rollback protection.)
-
 =item SSL_OP_ALL
 
 All of the above bug workarounds.
 
 =back
 
-It is save and recommended to use SSL_OP_ALL to enable the bug workaround
+It is safe and recommended to use B<SSL_OP_ALL> to enable the bug workaround
 options.
 
 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 DH parameters.
+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
 
-Also use the temporary RSA key when doing RSA operations.
+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 his list of preferences to the client and the client chooses.
 
 =item SSL_OP_PKCS1_CHECK_1
 
@@ -142,11 +171,6 @@ If we accept a netscape connection, demand a client cert, have a
 non-self-sighed CA which does not have it's CA in netscape, and the
 browser has a cert, it will crash/hang.  Works for 3.x and 4.xbeta 
 
-=item SSL_OP_NON_EXPORT_FIRST
-
-On servers try to use non-export (stronger) ciphers first. This option does
-not work under all circumstances (in the code it is declared "broken").
-
 =item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
 
 ...
@@ -163,6 +187,12 @@ Do not use the SSLv3 protocol.
 
 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
@@ -174,10 +204,19 @@ 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(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
 
-SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6.
+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.
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod
new file mode 100644
index 00000000000..1d0526d59a3
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod
@@ -0,0 +1,63 @@
+=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(SSL_CTX *ctx);
+
+ void SSL_set_quiet_shutdown(SSL *ssl, int mode);
+ int SSL_get_quiet_shutdown(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/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod
index 8bbfc787209..9aa6c6b2e39 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod
@@ -97,6 +97,7 @@ 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_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)>,
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod
index 21faed12d42..e3de27c4736 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod
@@ -37,7 +37,10 @@ L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either
 directly by the application or automatically (see
 L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>)
 
-The default value for session timeout is 300 seconds.
+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
 
@@ -50,6 +53,7 @@ SSL_CTX_get_timeout() returns the currently set timeout value.
 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_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
+L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
new file mode 100644
index 00000000000..29d1f8a6fbf
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -0,0 +1,170 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
new file mode 100644
index 00000000000..f85775927dd
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
@@ -0,0 +1,166 @@
+=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/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod b/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod
index fc0b76118fd..5bb21ca5357 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod
@@ -59,14 +59,14 @@ The handshake will be continued regardless of the verification result.
 
 B<Server mode:> the server sends a client certificate request to the client.
 The certificate returned (if any) is checked. If the verification process
-fails as indicated by B<verify_callback>, the TLS/SSL handshake is
+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 as indicated by B<verify_callback>, the TLS/SSL handshake is
+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.
@@ -92,6 +92,15 @@ B<Client mode:> ignored
 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
@@ -278,6 +287,7 @@ 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)>
 
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod b/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod
index 3b2fe6fc508..b8868f18bfc 100644
--- a/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod
+++ b/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod
@@ -149,6 +149,7 @@ 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)>
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod b/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod
index df30ccbb320..558de01df91 100644
--- a/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod
+++ b/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod
@@ -16,10 +16,40 @@ 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.
 
-L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>
+=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/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod b/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod
index cd33b73aa35..ea3c2bcfe60 100644
--- a/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod
+++ b/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod
@@ -58,6 +58,7 @@ If any of the function is passed the NULL pointer for the session B<s>,
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>,
-L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(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/lib/libssl/src/doc/ssl/SSL_accept.pod b/lib/libssl/src/doc/ssl/SSL_accept.pod
index 86f980de41b..ac6caf9baaf 100644
--- a/lib/libssl/src/doc/ssl/SSL_accept.pod
+++ b/lib/libssl/src/doc/ssl/SSL_accept.pod
@@ -37,11 +37,6 @@ 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.
 
-When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it
-is necessary to call SSL_set_accept_state()
-before calling SSL_accept() to explicitly switch the B<ssl> to server
-mode.
-
 =head1 RETURN VALUES
 
 The following return values can occur:
diff --git a/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod b/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod
new file mode 100644
index 00000000000..94e28cc3075
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod
@@ -0,0 +1,228 @@
+=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/lib/libssl/src/doc/ssl/SSL_clear.pod b/lib/libssl/src/doc/ssl/SSL_clear.pod
index 8b735d81dcb..8e077e31c9a 100644
--- a/lib/libssl/src/doc/ssl/SSL_clear.pod
+++ b/lib/libssl/src/doc/ssl/SSL_clear.pod
@@ -25,6 +25,25 @@ 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:
@@ -44,6 +63,7 @@ The SSL_clear() operation was successful.
 
 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_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/lib/libssl/src/doc/ssl/SSL_connect.pod b/lib/libssl/src/doc/ssl/SSL_connect.pod
index bcc167745b8..766f1876aaf 100644
--- a/lib/libssl/src/doc/ssl/SSL_connect.pod
+++ b/lib/libssl/src/doc/ssl/SSL_connect.pod
@@ -34,11 +34,6 @@ 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.
 
-When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it
-is necessary to call L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
-before calling SSL_connect() to explicitly switch the B<ssl> to client
-mode.
-
 =head1 RETURN VALUES
 
 The following return values can occur:
diff --git a/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod b/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod
new file mode 100644
index 00000000000..52d0227b193
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod
@@ -0,0 +1,26 @@
+=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(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/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod b/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod
index 40e01cf9c81..5693fdebb2f 100644
--- a/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod
+++ b/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod
@@ -47,6 +47,7 @@ the server did not send a list of CAs (client mode).
 =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_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/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod b/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod
new file mode 100644
index 00000000000..8d43b31345d
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod
@@ -0,0 +1,41 @@
+=pod
+
+=head1 NAME
+
+SSL_get_default_timeout - get default session timeout value
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_default_timeout(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/lib/libssl/src/doc/ssl/SSL_get_error.pod b/lib/libssl/src/doc/ssl/SSL_get_error.pod
index d95eec78aa1..f700bf0ace5 100644
--- a/lib/libssl/src/doc/ssl/SSL_get_error.pod
+++ b/lib/libssl/src/doc/ssl/SSL_get_error.pod
@@ -69,13 +69,13 @@ 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
+=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(). The SSL function should be
-called again when the connection is established. This messages can only
-appear with a BIO_s_connect() BIO.
+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.
diff --git a/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod b/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod
index 18d1db5183b..60635a96600 100644
--- a/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod
+++ b/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod
@@ -19,7 +19,7 @@ peer presented. If the peer did not present a certificate, NULL is returned.
 
 Due to the protocol definition, a TLS/SSL server will always send a
 certificate, if present. A client will only send a certificate when
-explicitely requested to do so by the server (see
+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.
 
diff --git a/lib/libssl/src/doc/ssl/SSL_get_session.pod b/lib/libssl/src/doc/ssl/SSL_get_session.pod
index a0266e2ac63..dd9aba40b6a 100644
--- a/lib/libssl/src/doc/ssl/SSL_get_session.pod
+++ b/lib/libssl/src/doc/ssl/SSL_get_session.pod
@@ -37,8 +37,16 @@ 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 and the session will stay in memory until explicitly freed with
-L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, regardless of its state.
+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
 
diff --git a/lib/libssl/src/doc/ssl/SSL_new.pod b/lib/libssl/src/doc/ssl/SSL_new.pod
index 3b084e867d0..25300e978f0 100644
--- a/lib/libssl/src/doc/ssl/SSL_new.pod
+++ b/lib/libssl/src/doc/ssl/SSL_new.pod
@@ -38,6 +38,7 @@ The return value points to an allocated SSL structure.
 
 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/lib/libssl/src/doc/ssl/SSL_read.pod b/lib/libssl/src/doc/ssl/SSL_read.pod
index cc7aa1a5476..f6c37f77e49 100644
--- a/lib/libssl/src/doc/ssl/SSL_read.pod
+++ b/lib/libssl/src/doc/ssl/SSL_read.pod
@@ -25,11 +25,10 @@ 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 not the case if a generic
-method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that
+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()
-must be used before the first call to an SSL_read() or
-L<SSL_write(3)|SSL_write(3)> function).
+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
@@ -84,9 +83,20 @@ bytes actually read from the TLS/SSL connection.
 
 =item 0
 
-The read operation was not successful, probably because no data was
-available. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred.
+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
 
@@ -102,6 +112,7 @@ 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/lib/libssl/src/doc/ssl/SSL_rstate_string.pod b/lib/libssl/src/doc/ssl/SSL_rstate_string.pod
new file mode 100644
index 00000000000..bdb8a1fcd55
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_rstate_string.pod
@@ -0,0 +1,59 @@
+=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/lib/libssl/src/doc/ssl/SSL_session_reused.pod b/lib/libssl/src/doc/ssl/SSL_session_reused.pod
new file mode 100644
index 00000000000..da7d06264d0
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_session_reused.pod
@@ -0,0 +1,45 @@
+=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/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod b/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod
index a8c4463c640..7adf8adfed1 100644
--- a/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod
+++ b/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod
@@ -14,9 +14,9 @@ SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in clie
 
 =head1 DESCRIPTION
 
-SSL_set_connect_state() B<ssl> to work in client mode.
+SSL_set_connect_state() sets B<ssl> to work in client mode.
 
-SSL_set_accept_state() B<ssl> to work in server mode.
+SSL_set_accept_state() sets B<ssl> to work in server mode.
 
 =head1 NOTES
 
@@ -27,12 +27,17 @@ 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().)
 
-In order to successfully accomplish the handshake, the SSL routines need
-to know whether they should act in server or client mode. If the generic
-method was used, this is not clear from the method itself and must be set
-with either SSL_set_connect_state() or SSL_set_accept_state(). If these
-routines are not called, the default value set when L<SSL_new(3)|SSL_new(3)>
-is called is server mode.
+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
 
@@ -42,6 +47,8 @@ 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_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>
 
 =cut
diff --git a/lib/libssl/src/doc/ssl/SSL_set_session.pod b/lib/libssl/src/doc/ssl/SSL_set_session.pod
index c4f7878579d..5f54714ad86 100644
--- a/lib/libssl/src/doc/ssl/SSL_set_session.pod
+++ b/lib/libssl/src/doc/ssl/SSL_set_session.pod
@@ -16,12 +16,21 @@ 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().
+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:
@@ -41,6 +50,8 @@ The operation succeeded.
 =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/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod b/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod
index 6b196c1f15b..6289e635d96 100644
--- a/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod
+++ b/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod
@@ -46,7 +46,10 @@ 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.
+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)>).
 
@@ -63,6 +66,7 @@ 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/lib/libssl/src/doc/ssl/SSL_shutdown.pod b/lib/libssl/src/doc/ssl/SSL_shutdown.pod
index c4ae6704e70..6b5012be7a8 100644
--- a/lib/libssl/src/doc/ssl/SSL_shutdown.pod
+++ b/lib/libssl/src/doc/ssl/SSL_shutdown.pod
@@ -22,10 +22,52 @@ 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 behaviour of SSL_shutdown() depends on the underlying BIO. 
+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 the 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 has been finished or an error occurred.
+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()
@@ -38,6 +80,12 @@ 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:
@@ -46,19 +94,23 @@ The following return values can occur:
 
 =item 1
 
-The shutdown was successfully completed.
+The shutdown was successfully completed. The "close notify" alert was sent
+and the peer's "close notify" alert was received.
 
 =item 0
 
-The shutdown was not successful. Call SSL_get_error() with the return
-value B<ret> to find out the reason.
+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 of
+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 SSL_get_error() with the return value B<ret> to find out the reason.
+Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret>
+to find out the reason.
 
 =back
 
@@ -66,6 +118,7 @@ Call SSL_get_error() with the return value B<ret> to find out the reason.
 
 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)>
 
diff --git a/lib/libssl/src/doc/ssl/SSL_state_string.pod b/lib/libssl/src/doc/ssl/SSL_state_string.pod
new file mode 100644
index 00000000000..b4be1aaa486
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_state_string.pod
@@ -0,0 +1,45 @@
+=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(SSL *ssl);
+ const char *SSL_state_string_long(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/lib/libssl/src/doc/ssl/SSL_want.pod b/lib/libssl/src/doc/ssl/SSL_want.pod
new file mode 100644
index 00000000000..50cc89db80b
--- /dev/null
+++ b/lib/libssl/src/doc/ssl/SSL_want.pod
@@ -0,0 +1,77 @@
+=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(SSL *ssl);
+ int SSL_want_nothing(SSL *ssl);
+ int SSL_want_read(SSL *ssl);
+ int SSL_want_write(SSL *ssl);
+ int SSL_want_x509_lookup(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/lib/libssl/src/doc/ssl/SSL_write.pod b/lib/libssl/src/doc/ssl/SSL_write.pod
index b0dfefae20d..dfa42e9aeef 100644
--- a/lib/libssl/src/doc/ssl/SSL_write.pod
+++ b/lib/libssl/src/doc/ssl/SSL_write.pod
@@ -25,11 +25,9 @@ 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 not the case if a generic
-method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that
+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()
-must be used before the first call to an L<SSL_read(3)|SSL_read(3)>
-or SSL_write() function.
+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
@@ -80,8 +78,14 @@ bytes actually written to the TLS/SSL connection.
 
 =item 0
 
-The write operation was not successful. Call SSL_get_error() with the return
-value B<ret> to find out, whether an error occurred.
+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
 
diff --git a/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod b/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod
index 9a1ba6c47b2..0321a5a36f2 100644
--- a/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod
+++ b/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod
@@ -30,7 +30,17 @@ 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.
+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
@@ -50,7 +60,7 @@ 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(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/lib/libssl/src/doc/ssl/ssl.pod b/lib/libssl/src/doc/ssl/ssl.pod
index 16292a05f22..ce41b3e17d2 100644
--- a/lib/libssl/src/doc/ssl/ssl.pod
+++ b/lib/libssl/src/doc/ssl/ssl.pod
@@ -299,7 +299,7 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =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)(SSL_CTX *), char *arg)
+=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);
 
@@ -317,6 +317,10 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =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);
@@ -576,6 +580,10 @@ connection defined in the B<SSL> structure.
 
 =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);
@@ -650,8 +658,10 @@ 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)>,
@@ -661,18 +671,32 @@ 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_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)>,
@@ -685,12 +709,19 @@ 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_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(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_pending(3)|SSL_pending(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_write(3)|SSL_write(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)>,