Version negotiation rewrite doc updates

Update various documentation references to the new TLS_*_method names. Also
add a CHANGES entry.

Reviewed-by: Kurt Roeckx <kurt@openssl.org>

diff --git a/CHANGES b/CHANGES
index 337b9b1364460b2ec00ac8cde51b73191ad4bb0c..8600b8166c7e3b29c3950aad47493da54b1f12fe 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -3,6 +3,15 @@
  _______________
 
  Changes between 1.0.2 and 1.1.0  [xx XXX xxxx]
+
+  *) Version negotiation has been rewritten. In particular SSLv23_method(),
+     SSLv23_client_method() and SSLv23_server_method() have been deprecated,
+     and turned into macros which simply call the new preferred function names
+     TLS_method(), TLS_client_method() and TLS_server_method(). All new code
+     should use the new names instead. Also as part of this change the ssl23.h
+     header file has been removed.
+     [Matt Caswell]
+
   *) Support for Kerberos ciphersuites in TLS (RFC2712) has been removed. This
      code and the associated standard is no longer considered fit-for-purpose.
      [Matt Caswell]

diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod
index a9f23f1dd7de74fee3b99995e117bfcbbf28e990..a0531b0e0e780ebdea92d500b958b9ba8ea73e72 100644 (file)
--- a/doc/crypto/BIO_f_ssl.pod
+++ b/doc/crypto/BIO_f_ssl.pod
@@ -148,7 +148,7 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
   * do it automatically
   */
 
- ctx = SSL_CTX_new(SSLv23_client_method());
+ ctx = SSL_CTX_new(TLS_client_method());
 
  /* We'd normally set some stuff like the verify paths and
   * mode here because as things stand this will connect to
@@ -212,7 +212,7 @@ a client and also echoes the request to standard output.
 
  /* Might seed PRNG here */
 
- ctx = SSL_CTX_new(SSLv23_server_method());
+ ctx = SSL_CTX_new(TLS_server_method());
 
  if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
        || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)

diff --git a/doc/crypto/err.pod b/doc/crypto/err.pod
index 4b10f59dfdc18477abde5db82b575fa0f6d751f1..1a19a19a80f89623ed7dea2ba2d8426945d64d1d 100644 (file)
--- a/doc/crypto/err.pod
+++ b/doc/crypto/err.pod
@@ -79,16 +79,16 @@ Each sub-library has a specific macro XXXerr() that is used to report
 errors. Its first argument is a function code B<XXX_F_...>, the second
 argument is a reason code B<XXX_R_...>. Function codes are derived
 from the function names; reason codes consist of textual error
-descriptions. For example, the function ssl23_read() reports a
+descriptions. For example, the function ssl3_read_bytes() reports a
 "handshake failure" as follows:
 
- SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
+ SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
 
 Function and reason codes should consist of upper case characters,
 numbers and underscores only. The error file generation script translates
 function codes into function names by looking in the header files
 for an appropriate function name, if none is found it just uses
-the capitalized form such as "SSL23_READ" in the above example.
+the capitalized form such as "SSL3_READ_BYTES" in the above example.
 
 The trailing section of a reason code (after the "_R_") is translated
 into lower case and underscores changed to spaces.

diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index 0da3f7be8e25eab8a50d03c25209217ade05a452..c788b9b1abd53e4f3abcf32fe54cb27532ba3dde 100644 (file)
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_CTX_new, 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
+SSL_CTX_new, 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, TLS_method, TLS_server_method, TLS_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
 
@@ -28,31 +28,30 @@ client only type. B<method> can be of the following types:
 A TLS/SSL connection established with these methods will only understand the
 SSLv3 protocol. A client will send out SSLv3 client hello messages
 and will indicate that it only understands SSLv3. A server will only understand
-SSLv3 client hello messages. This especially means, that it will
-not understand SSLv2 client hello messages which are widely used for
-compatibility reasons, see SSLv23_*_method().
+SSLv3 client hello messages.
 
 =item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)
 
 A TLS/SSL connection established with these methods will only understand the
 TLSv1 protocol. A client will send out TLSv1 client hello messages
 and will indicate that it only understands TLSv1. A server will only understand
-TLSv1 client hello messages. This especially means, that it will
-not understand SSLv2 client hello messages which are widely used for
-compatibility reasons, see SSLv23_*_method(). It will also not understand
-SSLv3 client hello messages.
+TLSv1 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.
+understand TLSv1.1 client hello messages.
 
-=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
+=item TLSv1_2_method(void), TLSv1_2_server_method(void), TLSv1_2_client_method(void)
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages
+and will indicate that it only understands TLSv1.2. A server will only
+understand TLSv1.2 client hello messages.
+
+=item TLS_method(void), TLS_server_method(void), TLS_client_method(void)
 
 A TLS/SSL connection established with these methods may understand the
 SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
@@ -63,6 +62,12 @@ 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.
 
+=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
+
+Use of these functions is deprecated. They have been replaced with TLS_Method(),
+TLS_server_method() and TLS_client_method() respectively. New code should use
+those functions instead.
+
 =back
 
 The list of protocols available can later be limited using the
@@ -98,7 +103,9 @@ The return value points to an allocated SSL_CTX object.
 =head1 HISTORY
 
 SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in
-OpenSSL 1.1.0.
+OpenSSL 1.1.0. SSLv23_method, SSLv23_server_method and SSLv23_client_method were
+deprecated and TLS_method, TLS_server_method and TLS_client_method
+were introduced in OpenSSL 1.1.0.
 
 =head1 SEE ALSO
 

diff --git a/doc/ssl/SSL_clear.pod b/doc/ssl/SSL_clear.pod
index ba192bd518aebed9e3a4089be7b5cab49ef6371d..1b9ea1f4fcfbdf7fc494dd47884c431ef561d091 100644 (file)
--- a/doc/ssl/SSL_clear.pod
+++ b/doc/ssl/SSL_clear.pod
@@ -30,7 +30,7 @@ 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
+server method, even if TLS_*_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.
 

diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 5af0fc63c6776dc5d91e119bff37b449ec22d998..a094356131d85c65be760066a8c7b4f589416954 100644 (file)
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -103,13 +103,6 @@ That's the sub header file dealing with the SSLv3 protocol only.
 I<Usually you don't have to include it explicitly because
 it's already included by ssl.h>.
 
-=item B<ssl23.h>
-
-That's the sub header file dealing with the combined use of different
-protocol version.
-I<Usually you don't have to include it explicitly because
-it's already included by ssl.h>.
-
 =item B<tls1.h>
 
 That's the sub header file dealing with the TLSv1 protocol only.