From b1fc43635eea9d87b5527d20617c711079fb4119 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 30 Nov 2016 15:48:53 +0000 Subject: 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. --- src/lib/libssl/man/SSL_CTX_new.3 | 218 +++++++++++++++++++++++++++++---------- 1 file changed, 164 insertions(+), 54 deletions(-) diff --git a/src/lib/libssl/man/SSL_CTX_new.3 b/src/lib/libssl/man/SSL_CTX_new.3 index 872d302b24..ee60f2a9f8 100644 --- a/src/lib/libssl/man/SSL_CTX_new.3 +++ b/src/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 -- cgit v1.2.3-55-g6feb