lib/libssl/man/SSL_CTX_new.3

   1 .\"     $OpenBSD: SSL_CTX_new.3,v 1.2 2016/11/30 15:48:53 schwarze Exp $
   2 .\"     OpenSSL 21cd6e00 Aug 17 15:21:33 2015 -0400
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: November 30 2016 $
  53 .Dt SSL_CTX_NEW 3
  54 .Os
  55 .Sh NAME
  56 .Nm SSL_CTX_new ,
  57 .Nm TLS_method ,
  58 .Nm TLS_server_method ,
  59 .Nm TLS_client_method ,
  60 .Nm SSLv23_method ,
  61 .Nm SSLv23_server_method ,
  62 .Nm SSLv23_client_method ,
  63 .Nm TLSv1_method ,
  64 .Nm TLSv1_server_method ,
  65 .Nm TLSv1_client_method ,
  66 .Nm TLSv1_1_method ,
  67 .Nm TLSv1_1_server_method ,
  68 .Nm TLSv1_1_client_method ,
  69 .Nm TLSv1_2_method ,
  70 .Nm TLSv1_2_server_method ,
  71 .Nm TLSv1_2_client_method ,
  72 .Nm DTLSv1_method ,
  73 .Nm DTLSv1_server_method ,
  74 .Nm DTLSv1_client_method
  75 .Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions
  76 .Sh SYNOPSIS
  77 .In openssl/ssl.h
  78 .Ft SSL_CTX *
  79 .Fn SSL_CTX_new "const SSL_METHOD *method"
  80 .Ft const SSL_METHOD *
  81 .Fn TLS_method void
  82 .Ft const SSL_METHOD *
  83 .Fn TLS_server_method void
  84 .Ft const SSL_METHOD *
  85 .Fn TLS_client_method void
  86 .Ft const SSL_METHOD *
  87 .Fn SSLv23_method void
  88 .Ft const SSL_METHOD *
  89 .Fn SSLv23_server_method void
  90 .Ft const SSL_METHOD *
  91 .Fn SSLv23_client_method void
  92 .Ft const SSL_METHOD *
  93 .Fn TLSv1_method void
  94 .Ft const SSL_METHOD *
  95 .Fn TLSv1_server_method void
  96 .Ft const SSL_METHOD *
  97 .Fn TLSv1_client_method void
  98 .Ft const SSL_METHOD *
  99 .Fn TLSv1_1_method void
 100 .Ft const SSL_METHOD *
 101 .Fn TLSv1_1_server_method void
 102 .Ft const SSL_METHOD *
 103 .Fn TLSv1_1_client_method void
 104 .Ft const SSL_METHOD *
 105 .Fn TLSv1_2_method void
 106 .Ft const SSL_METHOD *
 107 .Fn TLSv1_2_server_method void
 108 .Ft const SSL_METHOD *
 109 .Fn TLSv1_2_client_method void
 110 .Ft const SSL_METHOD *
 111 .Fn DTLSv1_method void
 112 .Ft const SSL_METHOD *
 113 .Fn DTLSv1_server_method void
 114 .Ft const SSL_METHOD *
 115 .Fn DTLSv1_client_method void
 116 .Sh DESCRIPTION
 117 .Fn SSL_CTX_new
 118 creates a new
 119 .Vt SSL_CTX
 120 object as framework to establish TLS/SSL or DTLS enabled connections.
 121 It initializes the list of ciphers, the session cache setting, the
 122 callbacks, the keys and certificates, and the options to its default
 123 values.
 124 .Pp
 125 The
 126 .Vt SSL_CTX
 127 object uses
 128 .Fa method
 129 as its connection method.
 130 The methods exist in a generic type (for client and server use),
 131 a server only type, and a client only type.
 132 .Fa method
 133 can be of the following types:
 134 .Bl -tag -width Ds
 135 .It Xo
 136 .Fn TLS_method ,
 137 .Fn TLS_server_method ,
 138 .Fn TLS_client_method
 139 .Xc
 140 These are the general-purpose version-flexible SSL/TLS methods.
 141 The actual protocol version used will be negotiated to the highest
 142 version mutually supported by the client and the server.
 143 The supported protocols are TLSv1, TLSv1.1 and TLSv1.2.
 144 Applications should use these methods and avoid the version-specific
 145 methods described below.
 146 .It Xo
 147 .Fn SSLv23_method ,
 148 .Fn SSLv23_server_method ,
 149 .Fn SSLv23_client_method
 150 .Xc
 151 Use of these functions is deprecated.
 152 They have been replaced with the above
 153 .Fn TLS_method ,
 154 .Fn TLS_server_method ,
 155 and
 156 .Fn TLS_client_method ,
 157 respectively.
 158 New code should use those functions instead.
 159 .It Xo
 160 .Fn TLSv1_method ,
 161 .Fn TLSv1_server_method ,
 162 .Fn TLSv1_client_method
 163 .Xc
 164 A TLS/SSL connection established with these methods will only
 165 understand the TLSv1 protocol.
 166 .It Xo
 167 .Fn TLSv1_1_method ,
 168 .Fn TLSv1_1_server_method ,
 169 .Fn TLSv1_1_client_method
 170 .Xc
 171 A TLS/SSL connection established with these methods will only
 172 understand the TLSv1.1 protocol.
 173 .It Xo
 174 .Fn TLSv1_2_method ,
 175 .Fn TLSv1_2_server_method ,
 176 .Fn TLSv1_2_client_method
 177 .Xc
 178 A TLS/SSL connection established with these methods will only
 179 understand the TLSv1.2 protocol.
 180 .It Xo
 181 .Fn DTLSv1_method ,
 182 .Fn DTLSv1_server_method ,
 183 .Fn DTLSv1_client_method
 184 .Xc
 185 These are the version-specific methods for DTLSv1.
 186 .El
 187 .Pp
 188 The list of protocols available can also be limited using the
 189 .Dv SSL_OP_NO_TLSv1 ,
 190 .Dv SSL_OP_NO_TLSv1_1 ,
 191 and
 192 .Dv SSL_OP_NO_TLSv1_2
 193 options of the
 194 .Xr SSL_CTX_set_options 3
 195 or
 196 .Xr SSL_set_options 3
 197 functions, but this approach is not recommended.
 198 Clients should avoid creating "holes" in the set of protocols they support.
 199 When disabling a protocol, make sure that you also disable either
 200 all previous or all subsequent protocol versions.
 201 In clients, when a protocol version is disabled without disabling
 202 all previous protocol versions, the effect is to also disable all
 203 subsequent protocol versions.
 204 .Sh RETURN VALUES
 205 The following return values can occur:
 206 .Bl -tag -width Ds
 207 .It Dv NULL
 208 The creation of a new
 209 .Vt SSL_CTX
 210 object failed.
 211 Check the error stack to find out the reason.
 212 .It Pointer to an SSL_CTX object
 213 The return value points to an allocated
 214 .Vt SSL_CTX
 215 object.
 216 .El
 217 .Sh SEE ALSO
 218 .Xr ssl 3 ,
 219 .Xr SSL_accept 3 ,
 220 .Xr SSL_CTX_free 3 ,
 221 .Xr SSL_set_connect_state 3