secure/lib/libcrypto/man/SSL_CTX_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_NEW 3"
 132 .TH SSL_CTX_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, SSL_CTX_new, SSL_CTX_up_ref, 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, DTLS_method, DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method \&\- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
 145 \& int SSL_CTX_up_ref(SSL_CTX *ctx);
 146 \&
 147 \& const SSL_METHOD *TLS_method(void);
 148 \& const SSL_METHOD *TLS_server_method(void);
 149 \& const SSL_METHOD *TLS_client_method(void);
 150 \&
 151 \& const SSL_METHOD *SSLv23_method(void);
 152 \& const SSL_METHOD *SSLv23_server_method(void);
 153 \& const SSL_METHOD *SSLv23_client_method(void);
 154 \&
 155 \& #ifndef OPENSSL_NO_SSL3_METHOD
 156 \& const SSL_METHOD *SSLv3_method(void);
 157 \& const SSL_METHOD *SSLv3_server_method(void);
 158 \& const SSL_METHOD *SSLv3_client_method(void);
 159 \& #endif
 160 \&
 161 \& #ifndef OPENSSL_NO_TLS1_METHOD
 162 \& const SSL_METHOD *TLSv1_method(void);
 163 \& const SSL_METHOD *TLSv1_server_method(void);
 164 \& const SSL_METHOD *TLSv1_client_method(void);
 165 \& #endif
 166 \&
 167 \& #ifndef OPENSSL_NO_TLS1_1_METHOD
 168 \& const SSL_METHOD *TLSv1_1_method(void);
 169 \& const SSL_METHOD *TLSv1_1_server_method(void);
 170 \& const SSL_METHOD *TLSv1_1_client_method(void);
 171 \& #endif
 172 \&
 173 \& #ifndef OPENSSL_NO_TLS1_2_METHOD
 174 \& const SSL_METHOD *TLSv1_2_method(void);
 175 \& const SSL_METHOD *TLSv1_2_server_method(void);
 176 \& const SSL_METHOD *TLSv1_2_client_method(void);
 177 \& #endif
 178 \&
 179 \& const SSL_METHOD *DTLS_method(void);
 180 \& const SSL_METHOD *DTLS_server_method(void);
 181 \& const SSL_METHOD *DTLS_client_method(void);
 182 \&
 183 \& #ifndef OPENSSL_NO_DTLS1_METHOD
 184 \& const SSL_METHOD *DTLSv1_method(void);
 185 \& const SSL_METHOD *DTLSv1_server_method(void);
 186 \& const SSL_METHOD *DTLSv1_client_method(void);
 187 \& #endif
 188 \&
 189 \& #ifndef OPENSSL_NO_DTLS1_2_METHOD
 190 \& const SSL_METHOD *DTLSv1_2_method(void);
 191 \& const SSL_METHOD *DTLSv1_2_server_method(void);
 192 \& const SSL_METHOD *DTLSv1_2_client_method(void);
 193 \& #endif
 194 .Ve
 195 .SH "DESCRIPTION"
 196 .IX Header "DESCRIPTION"
 197 \&\fISSL_CTX_new()\fR creates a new \fB\s-1SSL_CTX\s0\fR object as framework to
 198 establish \s-1TLS/SSL\s0 or \s-1DTLS\s0 enabled connections. An \fB\s-1SSL_CTX\s0\fR object is
 199 reference counted. Creating an \fB\s-1SSL_CTX\s0\fR object for the first time increments
 200 the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
 201 reference count drops to zero, any memory or resources allocated to the
 202 \&\fB\s-1SSL_CTX\s0\fR object are freed. \fISSL_CTX_up_ref()\fR increments the reference count for
 203 an existing \fB\s-1SSL_CTX\s0\fR structure.
 204 .SH "NOTES"
 205 .IX Header "NOTES"
 206 The \s-1SSL_CTX\s0 object uses \fBmethod\fR as connection method.
 207 The methods exist in a generic type (for client and server use), a server only
 208 type, and a client only type.
 209 \&\fBmethod\fR can be of the following types:
 210 .IP "\fITLS_method()\fR, \fITLS_server_method()\fR, \fITLS_client_method()\fR" 4
 211 .IX Item "TLS_method(), TLS_server_method(), TLS_client_method()"
 212 These are the general-purpose \fIversion-flexible\fR \s-1SSL/TLS\s0 methods.
 213 The actual protocol version used will be negotiated to the highest version
 214 mutually supported by the client and the server.
 215 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
 216 Applications should use these methods, and avoid the version-specific
 217 methods described below.
 218 .IP "\fISSLv23_method()\fR, \fISSLv23_server_method()\fR, \fISSLv23_client_method()\fR" 4
 219 .IX Item "SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()"
 220 Use of these functions is deprecated. They have been replaced with the above
 221 \&\fITLS_method()\fR, \fITLS_server_method()\fR and \fITLS_client_method()\fR respectively. New
 222 code should use those functions instead.
 223 .IP "\fITLSv1_2_method()\fR, \fITLSv1_2_server_method()\fR, \fITLSv1_2_client_method()\fR" 4
 224 .IX Item "TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()"
 225 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 226 TLSv1.2 protocol.
 227 .IP "\fITLSv1_1_method()\fR, \fITLSv1_1_server_method()\fR, \fITLSv1_1_client_method()\fR" 4
 228 .IX Item "TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()"
 229 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 230 TLSv1.1 protocol.
 231 .IP "\fITLSv1_method()\fR, \fITLSv1_server_method()\fR, \fITLSv1_client_method()\fR" 4
 232 .IX Item "TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()"
 233 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 234 TLSv1 protocol.
 235 .IP "\fISSLv3_method()\fR, \fISSLv3_server_method()\fR, \fISSLv3_client_method()\fR" 4
 236 .IX Item "SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()"
 237 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 238 SSLv3 protocol.
 239 The SSLv3 protocol is deprecated and should not be used.
 240 .IP "\fIDTLS_method()\fR, \fIDTLS_server_method()\fR, \fIDTLS_client_method()\fR" 4
 241 .IX Item "DTLS_method(), DTLS_server_method(), DTLS_client_method()"
 242 These are the version-flexible \s-1DTLS\s0 methods.
 243 Currently supported protocols are \s-1DTLS 1.0\s0 and \s-1DTLS 1.2.\s0
 244 .IP "\fIDTLSv1_2_method()\fR, \fIDTLSv1_2_server_method()\fR, \fIDTLSv1_2_client_method()\fR" 4
 245 .IX Item "DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()"
 246 These are the version-specific methods for DTLSv1.2.
 247 .IP "\fIDTLSv1_method()\fR, \fIDTLSv1_server_method()\fR, \fIDTLSv1_client_method()\fR" 4
 248 .IX Item "DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()"
 249 These are the version-specific methods for DTLSv1.
 250 .PP
 251 \&\fISSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, the
 252 callbacks, the keys and certificates and the options to their default values.
 253 .PP
 254 \&\fITLS_method()\fR, \fITLS_server_method()\fR, \fITLS_client_method()\fR, \fIDTLS_method()\fR,
 255 \&\fIDTLS_server_method()\fR and \fIDTLS_client_method()\fR are the \fIversion-flexible\fR
 256 methods.
 257 All other methods only support one specific protocol version.
 258 Use the \fIversion-flexible\fR methods instead of the version specific methods.
 259 .PP
 260 If you want to limit the supported protocols for the version flexible
 261 methods you can use \fISSL_CTX_set_min_proto_version\fR\|(3),
 262 \&\fISSL_set_min_proto_version\fR\|(3), \fISSL_CTX_set_max_proto_version\fR\|(3) and
 263 \&\fISSL_set_max_proto_version\fR\|(3) functions.
 264 Using these functions it is possible to choose e.g. \fITLS_server_method()\fR
 265 and be able to negotiate with all possible clients, but to only
 266 allow newer protocols like \s-1TLS 1.0, TLS 1.1, TLS 1.2\s0 or \s-1TLS 1.3.\s0
 267 .PP
 268 The list of protocols available can also be limited using the
 269 \&\fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, \fBSSL_OP_NO_TLSv1_1\fR,
 270 \&\fBSSL_OP_NO_TLSv1_3\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR
 271 options of the
 272 \&\fISSL_CTX_set_options\fR\|(3) or \fISSL_set_options\fR\|(3) functions, but this approach
 273 is not recommended. Clients should avoid creating \*(L"holes\*(R" in the set of
 274 protocols they support. When disabling a protocol, make sure that you also
 275 disable either all previous or all subsequent protocol versions.
 276 In clients, when a protocol version is disabled without disabling \fIall\fR
 277 previous protocol versions, the effect is to also disable all subsequent
 278 protocol versions.
 279 .PP
 280 The SSLv3 protocol is deprecated and should generally not be used.
 281 Applications should typically use \fISSL_CTX_set_min_proto_version\fR\|(3) to set
 282 the minimum protocol to at least \fB\s-1TLS1_VERSION\s0\fR.
 283 .SH "RETURN VALUES"
 284 .IX Header "RETURN VALUES"
 285 The following return values can occur:
 286 .IP "\s-1NULL\s0" 4
 287 .IX Item "NULL"
 288 The creation of a new \s-1SSL_CTX\s0 object failed. Check the error stack to find out
 289 the reason.
 290 .IP "Pointer to an \s-1SSL_CTX\s0 object" 4
 291 .IX Item "Pointer to an SSL_CTX object"
 292 The return value points to an allocated \s-1SSL_CTX\s0 object.
 293 .Sp
 294 \&\fISSL_CTX_up_ref()\fR returns 1 for success and 0 for failure.
 295 .SH "HISTORY"
 296 .IX Header "HISTORY"
 297 Support for SSLv2 and the corresponding \fISSLv2_method()\fR,
 298 \&\fISSLv2_server_method()\fR and \fISSLv2_client_method()\fR functions where
 299 removed in OpenSSL 1.1.0.
 300 .PP
 301 \&\fISSLv23_method()\fR, \fISSLv23_server_method()\fR and \fISSLv23_client_method()\fR
 302 were deprecated and the preferred \fITLS_method()\fR, \fITLS_server_method()\fR
 303 and \fITLS_client_method()\fR functions were introduced in OpenSSL 1.1.0.
 304 .PP
 305 All version-specific methods were deprecated in OpenSSL 1.1.0.
 306 .SH "SEE ALSO"
 307 .IX Header "SEE ALSO"
 308 \&\fISSL_CTX_set_options\fR\|(3), \fISSL_CTX_free\fR\|(3), \fISSL_accept\fR\|(3),
 309 \&\fISSL_CTX_set_min_proto_version\fR\|(3), \fIssl\fR\|(7), \fISSL_set_connect_state\fR\|(3)
 310 .SH "COPYRIGHT"
 311 .IX Header "COPYRIGHT"
 312 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 313 .PP
 314 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 315 this file except in compliance with the License.  You can obtain a copy
 316 in the file \s-1LICENSE\s0 in the source distribution or at
 317 <https://www.openssl.org/source/license.html>.