X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fssl%2FSSL_CTX_new.pod;h=7593cf60cf231ba26bd85b9d509cc413a1c1a967;hp=1dae8b0bdd02e2a1c048bd410bf126cc8734a24b;hb=aa224e9719871f89f962061a5970b49f03c9dca0;hpb=b72ff47037804dfbe5ed884c59a68de6fe475821

diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index 1dae8b0bdd..7593cf60cf 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -2,13 +2,13 @@
 
 =head1 NAME
 
-SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions
+SSL_CTX_new, SSLv2_method, SSLv2_server_method, SSLv2_client_method, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method - create a new SSL_CTX object as framework for TLS/SSL enabled functions
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
- SSL_CTX *SSL_CTX_new(SSL_METHOD *method);
+ SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
 
 =head1 DESCRIPTION
 
@@ -28,7 +28,8 @@ client only type. B<method> can be of the following types:
 A TLS/SSL connection established with these methods will only understand
 the SSLv2 protocol. A client will send out SSLv2 client hello messages
 and will also indicate that it only understand SSLv2. A server will only
-understand SSLv2 client hello messages.
+understand SSLv2 client hello messages. The SSLv2 protocol is deprecated 
+and very broken: its use is B<strongly> discouraged.
 
 =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
 
@@ -49,28 +50,48 @@ not understand SSLv2 client hello messages which are widely used for
 compatibility reasons, see SSLv23_*_method(). It will also not understand
 SSLv3 client hello messages.
 
+=item TLSv1_1_method(void), TLSv1_1_server_method(void), TLSv1_1_client_method(void)
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages
+and will indicate that it only understands TLSv1.1. A server will only
+understand TLSv1.1 client hello messages. This especially means, that it will
+not understand SSLv2 client hello messages which are widely used for
+compatibility reasons, see SSLv23_*_method(). It will also not understand
+SSLv3 client hello messages.
+
 =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
 
-A TLS/SSL connection established with these methods will understand the SSLv2,
-SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages
-and will indicate that it also understands SSLv3 and TLSv1. A server will
-understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best
-choice when compatibility is a concern.
+A TLS/SSL connection established with these methods may understand the SSLv2,
+SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
 
-=back
+If the cipher list does not contain any SSLv2 ciphersuites (the default
+cipher list does not) or extensions are required (for example server name)
+a client will send out TLSv1 client hello messages including extensions and
+will indicate that it also understands TLSv1.1, TLSv1.2 and permits a
+fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2
+protocols. This is the best choice when compatibility is a concern.
 
-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().
+If any SSLv2 ciphersuites are included in the cipher list and no extensions
+are required then SSLv2 compatible client hellos will be used by clients and
+SSLv2 will be accepted by servers. This is B<not> recommended due to the
+insecurity of SSLv2 and the limited nature of the SSLv2 client hello
+prohibiting the use of extensions.
+
+=back
 
 The list of protocols available can later be limited using the SSL_OP_NO_SSLv2,
-SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or
-B<SSL_set_options()> functions. Using these options it is possible to choose
-e.g. SSLv23_server_method() and be able to negotiate with all possible
-clients, but to only allow newer protocols like SSLv3 or TLSv1.
+SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2
+options of the SSL_CTX_set_options() or SSL_set_options() functions.
+Using these options it is possible to choose e.g. SSLv23_server_method() and
+be able to negotiate with all possible clients, but to only allow newer
+protocols like TLSv1, TLSv1.1 or TLS v1.2.
+
+Applications which never want to support SSLv2 (even is the cipher string
+is configured to use SSLv2 ciphersuites) can set SSL_OP_NO_SSLv2.
 
 SSL_CTX_new() initializes the list of ciphers, the session cache setting,
-the callbacks, the keys and certificates, and the options to its default
+the callbacks, the keys and certificates and the options to its default
 values.
 
 =head1 RETURN VALUES