Add Copyright and license.

Remove the last traces of SSLv3.
Add TLS_method(3), TLSv1_2_method(3), DTLSv1_method(3) and friends.
Add missing prototypes to the SYNOPSIS.
Merge additional information from OpenSSL.
Simplify description of TLSv1_method(3) and SSLv23_method(3), from OpenSSL.
Some additional minor fixes.

1 files changed, 164 insertions, 54 deletions

diff --git a/lib/libssl/man/SSL_CTX_new.3 b/lib/libssl/man/SSL_CTX_new.3
index 872d302b24d..ee60f2a9f8f 100644
--- a/lib/libssl/man/SSL_CTX_new.3
+++ b/lib/libssl/man/SSL_CTX_new.3
@@ -1,34 +1,127 @@
+.\"	$OpenBSD: SSL_CTX_new.3,v 1.2 2016/11/30 15:48:53 schwarze Exp $
+.\"	OpenSSL 21cd6e00 Aug 17 15:21:33 2015 -0400
 .\"
-.\"	$OpenBSD: SSL_CTX_new.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
+.\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
 .\"
-.Dd $Mdocdate: November 5 2016 $
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: November 30 2016 $
 .Dt SSL_CTX_NEW 3
 .Os
 .Sh NAME
 .Nm SSL_CTX_new ,
-.Nm SSLv3_method ,
-.Nm SSLv3_server_method ,
-.Nm SSLv3_client_method ,
+.Nm TLS_method ,
+.Nm TLS_server_method ,
+.Nm TLS_client_method ,
+.Nm SSLv23_method ,
+.Nm SSLv23_server_method ,
+.Nm SSLv23_client_method ,
 .Nm TLSv1_method ,
 .Nm TLSv1_server_method ,
 .Nm TLSv1_client_method ,
 .Nm TLSv1_1_method ,
 .Nm TLSv1_1_server_method ,
 .Nm TLSv1_1_client_method ,
-.Nm SSLv23_method ,
-.Nm SSLv23_server_method ,
-.Nm SSLv23_client_method
+.Nm TLSv1_2_method ,
+.Nm TLSv1_2_server_method ,
+.Nm TLSv1_2_client_method ,
+.Nm DTLSv1_method ,
+.Nm DTLSv1_server_method ,
+.Nm DTLSv1_client_method
 .Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions
 .Sh SYNOPSIS
 .In openssl/ssl.h
 .Ft SSL_CTX *
 .Fn SSL_CTX_new "const SSL_METHOD *method"
+.Ft const SSL_METHOD *
+.Fn TLS_method void
+.Ft const SSL_METHOD *
+.Fn TLS_server_method void
+.Ft const SSL_METHOD *
+.Fn TLS_client_method void
+.Ft const SSL_METHOD *
+.Fn SSLv23_method void
+.Ft const SSL_METHOD *
+.Fn SSLv23_server_method void
+.Ft const SSL_METHOD *
+.Fn SSLv23_client_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_server_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_client_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_1_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_1_server_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_1_client_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_2_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_2_server_method void
+.Ft const SSL_METHOD *
+.Fn TLSv1_2_client_method void
+.Ft const SSL_METHOD *
+.Fn DTLSv1_method void
+.Ft const SSL_METHOD *
+.Fn DTLSv1_server_method void
+.Ft const SSL_METHOD *
+.Fn DTLSv1_client_method void
 .Sh DESCRIPTION
 .Fn SSL_CTX_new
 creates a new
 .Vt SSL_CTX
-object as framework to establish TLS/SSL enabled connections.
-.Sh NOTES
+object as framework to establish TLS/SSL or DTLS enabled connections.
+It initializes the list of ciphers, the session cache setting, the
+callbacks, the keys and certificates, and the options to its default
+values.
+.Pp
 The
 .Vt SSL_CTX
 object uses
@@ -39,58 +132,75 @@ a server only type, and a client only type.
 .Fa method
 can be of the following types:
 .Bl -tag -width Ds
-.It Fn SSLv3_method void , Fn SSLv3_server_method void , \
-Fn SSLv3_client_method void
-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.
-Importantly, this means that it will not understand SSLv2 client hello messages
-which are widely used for compatibility reasons; see
-.Fn SSLv23_*_method .
-.It Fn TLSv1_method void , Fn TLSv1_server_method void , \
-Fn 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.
-Importantly, this means that it will not understand SSLv2 client hello messages
-which are widely used for compatibility reasons; see
-.Fn SSLv23_*_method .
-It will also not understand SSLv3 client hello messages.
-.It Fn SSLv23_method void , Fn SSLv23_server_method void , \
-Fn SSLv23_client_method void
-A TLS/SSL connection established with these methods may understand the SSLv3,
-TLSv1, TLSv1.1 and TLSv1.2 protocols.
-.Pp
-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.
+.It Xo
+.Fn TLS_method ,
+.Fn TLS_server_method ,
+.Fn TLS_client_method
+.Xc
+These are the general-purpose version-flexible SSL/TLS methods.
+The actual protocol version used will be negotiated to the highest
+version mutually supported by the client and the server.
+The supported protocols are TLSv1, TLSv1.1 and TLSv1.2.
+Applications should use these methods and avoid the version-specific
+methods described below.
+.It Xo
+.Fn SSLv23_method ,
+.Fn SSLv23_server_method ,
+.Fn SSLv23_client_method
+.Xc
+Use of these functions is deprecated.
+They have been replaced with the above
+.Fn TLS_method ,
+.Fn TLS_server_method ,
+and
+.Fn TLS_client_method ,
+respectively.
+New code should use those functions instead.
+.It Xo
+.Fn TLSv1_method ,
+.Fn TLSv1_server_method ,
+.Fn TLSv1_client_method
+.Xc
+A TLS/SSL connection established with these methods will only
+understand the TLSv1 protocol.
+.It Xo
+.Fn TLSv1_1_method ,
+.Fn TLSv1_1_server_method ,
+.Fn TLSv1_1_client_method
+.Xc
+A TLS/SSL connection established with these methods will only
+understand the TLSv1.1 protocol.
+.It Xo
+.Fn TLSv1_2_method ,
+.Fn TLSv1_2_server_method ,
+.Fn TLSv1_2_client_method
+.Xc
+A TLS/SSL connection established with these methods will only
+understand the TLSv1.2 protocol.
+.It Xo
+.Fn DTLSv1_method ,
+.Fn DTLSv1_server_method ,
+.Fn DTLSv1_client_method
+.Xc
+These are the version-specific methods for DTLSv1.
 .El
 .Pp
-The list of protocols available can later be limited using the
-.Dv SSL_OP_NO_SSLv3 ,
+The list of protocols available can also be limited using the
 .Dv SSL_OP_NO_TLSv1 ,
 .Dv SSL_OP_NO_TLSv1_1 ,
 and
 .Dv SSL_OP_NO_TLSv1_2
 options of the
-.Fn SSL_CTX_set_options
+.Xr SSL_CTX_set_options 3
 or
-.Fn SSL_set_options
-functions.
-Using these options it is possible to choose, for example,
-.Fn 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.
-.Pp
-.Fn SSL_CTX_new
-initializes the list of ciphers, the session cache setting, the callbacks,
-the keys and certificates, and the options to its default values.
+.Xr SSL_set_options 3
+functions, but this approach is not recommended.
+Clients should avoid creating "holes" in the set of protocols they support.
+When disabling a protocol, make sure that you also disable either
+all previous or all subsequent protocol versions.
+In clients, when a protocol version is disabled without disabling
+all previous protocol versions, the effect is to also disable all
+subsequent protocol versions.
 .Sh RETURN VALUES
 The following return values can occur:
 .Bl -tag -width Ds