Commit a27e81ee authored by Matt Caswell's avatar Matt Caswell
Browse files

Version negotiation rewrite doc updates 



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

Reviewed-by: default avatarKurt Roeckx <kurt@openssl.org>
parent a3680c8f

CHANGES

+9 −0
Original line number Diff line number Diff line
@@ -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]

doc/crypto/BIO_f_ssl.pod

+2 −2
Original line number Diff line number Diff line
@@ -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)

doc/crypto/err.pod

+3 −3
Original line number Diff line number Diff line
@@ -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.

doc/ssl/SSL_CTX_new.pod

+21 −14
Original line number Diff line number Diff line
@@ -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

doc/ssl/SSL_clear.pod

+1 −1
Original line number Diff line number Diff line
@@ -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.