secure/lib/libcrypto/man/SSL_CTX_new.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_NEW 3"
 136 .TH SSL_CTX_NEW 3 "2019-09-10" "1.1.1d" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
 149 \& int SSL_CTX_up_ref(SSL_CTX *ctx);
 150 \&
 151 \& const SSL_METHOD *TLS_method(void);
 152 \& const SSL_METHOD *TLS_server_method(void);
 153 \& const SSL_METHOD *TLS_client_method(void);
 154 \&
 155 \& const SSL_METHOD *SSLv23_method(void);
 156 \& const SSL_METHOD *SSLv23_server_method(void);
 157 \& const SSL_METHOD *SSLv23_client_method(void);
 158 \&
 159 \& #ifndef OPENSSL_NO_SSL3_METHOD
 160 \& const SSL_METHOD *SSLv3_method(void);
 161 \& const SSL_METHOD *SSLv3_server_method(void);
 162 \& const SSL_METHOD *SSLv3_client_method(void);
 163 \& #endif
 164 \&
 165 \& #ifndef OPENSSL_NO_TLS1_METHOD
 166 \& const SSL_METHOD *TLSv1_method(void);
 167 \& const SSL_METHOD *TLSv1_server_method(void);
 168 \& const SSL_METHOD *TLSv1_client_method(void);
 169 \& #endif
 170 \&
 171 \& #ifndef OPENSSL_NO_TLS1_1_METHOD
 172 \& const SSL_METHOD *TLSv1_1_method(void);
 173 \& const SSL_METHOD *TLSv1_1_server_method(void);
 174 \& const SSL_METHOD *TLSv1_1_client_method(void);
 175 \& #endif
 176 \&
 177 \& #ifndef OPENSSL_NO_TLS1_2_METHOD
 178 \& const SSL_METHOD *TLSv1_2_method(void);
 179 \& const SSL_METHOD *TLSv1_2_server_method(void);
 180 \& const SSL_METHOD *TLSv1_2_client_method(void);
 181 \& #endif
 182 \&
 183 \& const SSL_METHOD *DTLS_method(void);
 184 \& const SSL_METHOD *DTLS_server_method(void);
 185 \& const SSL_METHOD *DTLS_client_method(void);
 186 \&
 187 \& #ifndef OPENSSL_NO_DTLS1_METHOD
 188 \& const SSL_METHOD *DTLSv1_method(void);
 189 \& const SSL_METHOD *DTLSv1_server_method(void);
 190 \& const SSL_METHOD *DTLSv1_client_method(void);
 191 \& #endif
 192 \&
 193 \& #ifndef OPENSSL_NO_DTLS1_2_METHOD
 194 \& const SSL_METHOD *DTLSv1_2_method(void);
 195 \& const SSL_METHOD *DTLSv1_2_server_method(void);
 196 \& const SSL_METHOD *DTLSv1_2_client_method(void);
 197 \& #endif
 198 .Ve
 199 .SH "DESCRIPTION"
 200 .IX Header "DESCRIPTION"
 201 \&\fBSSL_CTX_new()\fR creates a new \fB\s-1SSL_CTX\s0\fR object as framework to
 202 establish \s-1TLS/SSL\s0 or \s-1DTLS\s0 enabled connections. An \fB\s-1SSL_CTX\s0\fR object is
 203 reference counted. Creating an \fB\s-1SSL_CTX\s0\fR object for the first time increments
 204 the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
 205 reference count drops to zero, any memory or resources allocated to the
 206 \&\fB\s-1SSL_CTX\s0\fR object are freed. \fBSSL_CTX_up_ref()\fR increments the reference count for
 207 an existing \fB\s-1SSL_CTX\s0\fR structure.
 208 .SH "NOTES"
 209 .IX Header "NOTES"
 210 The \s-1SSL_CTX\s0 object uses \fBmethod\fR as connection method.
 211 The methods exist in a generic type (for client and server use), a server only
 212 type, and a client only type.
 213 \&\fBmethod\fR can be of the following types:
 214 .IP "\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR" 4
 215 .IX Item "TLS_method(), TLS_server_method(), TLS_client_method()"
 216 These are the general-purpose \fIversion-flexible\fR \s-1SSL/TLS\s0 methods.
 217 The actual protocol version used will be negotiated to the highest version
 218 mutually supported by the client and the server.
 219 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
 220 Applications should use these methods, and avoid the version-specific
 221 methods described below, which are deprecated.
 222 .IP "\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR, \fBSSLv23_client_method()\fR" 4
 223 .IX Item "SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()"
 224 These functions do not exist anymore, they have been renamed to
 225 \&\fBTLS_method()\fR, \fBTLS_server_method()\fR and \fBTLS_client_method()\fR respectively.
 226 Currently, the old function calls are renamed to the corresponding new
 227 ones by preprocessor macros, to ensure that existing code which uses the
 228 old function names still compiles. However, using the old function names
 229 is deprecated and new code should call the new functions instead.
 230 .IP "\fBTLSv1_2_method()\fR, \fBTLSv1_2_server_method()\fR, \fBTLSv1_2_client_method()\fR" 4
 231 .IX Item "TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()"
 232 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 233 TLSv1.2 protocol. These methods are deprecated.
 234 .IP "\fBTLSv1_1_method()\fR, \fBTLSv1_1_server_method()\fR, \fBTLSv1_1_client_method()\fR" 4
 235 .IX Item "TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()"
 236 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 237 TLSv1.1 protocol.  These methods are deprecated.
 238 .IP "\fBTLSv1_method()\fR, \fBTLSv1_server_method()\fR, \fBTLSv1_client_method()\fR" 4
 239 .IX Item "TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()"
 240 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 241 TLSv1 protocol. These methods are deprecated.
 242 .IP "\fBSSLv3_method()\fR, \fBSSLv3_server_method()\fR, \fBSSLv3_client_method()\fR" 4
 243 .IX Item "SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()"
 244 A \s-1TLS/SSL\s0 connection established with these methods will only understand the
 245 SSLv3 protocol.
 246 The SSLv3 protocol is deprecated and should not be used.
 247 .IP "\fBDTLS_method()\fR, \fBDTLS_server_method()\fR, \fBDTLS_client_method()\fR" 4
 248 .IX Item "DTLS_method(), DTLS_server_method(), DTLS_client_method()"
 249 These are the version-flexible \s-1DTLS\s0 methods.
 250 Currently supported protocols are \s-1DTLS 1.0\s0 and \s-1DTLS 1.2.\s0
 251 .IP "\fBDTLSv1_2_method()\fR, \fBDTLSv1_2_server_method()\fR, \fBDTLSv1_2_client_method()\fR" 4
 252 .IX Item "DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()"
 253 These are the version-specific methods for DTLSv1.2.
 254 These methods are deprecated.
 255 .IP "\fBDTLSv1_method()\fR, \fBDTLSv1_server_method()\fR, \fBDTLSv1_client_method()\fR" 4
 256 .IX Item "DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()"
 257 These are the version-specific methods for DTLSv1.
 258 These methods are deprecated.
 259 .PP
 260 \&\fBSSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, the
 261 callbacks, the keys and certificates and the options to their default values.
 262 .PP
 263 \&\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR, \fBDTLS_method()\fR,
 264 \&\fBDTLS_server_method()\fR and \fBDTLS_client_method()\fR are the \fIversion-flexible\fR
 265 methods.
 266 All other methods only support one specific protocol version.
 267 Use the \fIversion-flexible\fR methods instead of the version specific methods.
 268 .PP
 269 If you want to limit the supported protocols for the version flexible
 270 methods you can use \fBSSL_CTX_set_min_proto_version\fR\|(3),
 271 \&\fBSSL_set_min_proto_version\fR\|(3), \fBSSL_CTX_set_max_proto_version\fR\|(3) and
 272 \&\fBSSL_set_max_proto_version\fR\|(3) functions.
 273 Using these functions it is possible to choose e.g. \fBTLS_server_method()\fR
 274 and be able to negotiate with all possible clients, but to only
 275 allow newer protocols like \s-1TLS 1.0, TLS 1.1, TLS 1.2\s0 or \s-1TLS 1.3.\s0
 276 .PP
 277 The list of protocols available can also be limited using the
 278 \&\fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, \fBSSL_OP_NO_TLSv1_1\fR,
 279 \&\fBSSL_OP_NO_TLSv1_3\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR
 280 options of the
 281 \&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions, but this approach
 282 is not recommended. Clients should avoid creating \*(L"holes\*(R" in the set of
 283 protocols they support. When disabling a protocol, make sure that you also
 284 disable either all previous or all subsequent protocol versions.
 285 In clients, when a protocol version is disabled without disabling \fIall\fR
 286 previous protocol versions, the effect is to also disable all subsequent
 287 protocol versions.
 288 .PP
 289 The SSLv3 protocol is deprecated and should generally not be used.
 290 Applications should typically use \fBSSL_CTX_set_min_proto_version\fR\|(3) to set
 291 the minimum protocol to at least \fB\s-1TLS1_VERSION\s0\fR.
 292 .SH "RETURN VALUES"
 293 .IX Header "RETURN VALUES"
 294 The following return values can occur:
 295 .IP "\s-1NULL\s0" 4
 296 .IX Item "NULL"
 297 The creation of a new \s-1SSL_CTX\s0 object failed. Check the error stack to find out
 298 the reason.
 299 .IP "Pointer to an \s-1SSL_CTX\s0 object" 4
 300 .IX Item "Pointer to an SSL_CTX object"
 301 The return value points to an allocated \s-1SSL_CTX\s0 object.
 302 .Sp
 303 \&\fBSSL_CTX_up_ref()\fR returns 1 for success and 0 for failure.
 304 .SH "SEE ALSO"
 305 .IX Header "SEE ALSO"
 306 \&\fBSSL_CTX_set_options\fR\|(3), \fBSSL_CTX_free\fR\|(3), \fBSSL_accept\fR\|(3),
 307 \&\fBSSL_CTX_set_min_proto_version\fR\|(3), \fBssl\fR\|(7), \fBSSL_set_connect_state\fR\|(3)
 308 .SH "HISTORY"
 309 .IX Header "HISTORY"
 310 Support for SSLv2 and the corresponding \fBSSLv2_method()\fR,
 311 \&\fBSSLv2_server_method()\fR and \fBSSLv2_client_method()\fR functions where
 312 removed in OpenSSL 1.1.0.
 313 .PP
 314 \&\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR and \fBSSLv23_client_method()\fR
 315 were deprecated and the preferred \fBTLS_method()\fR, \fBTLS_server_method()\fR
 316 and \fBTLS_client_method()\fR functions were added in OpenSSL 1.1.0.
 317 .PP
 318 All version-specific methods were deprecated in OpenSSL 1.1.0.
 319 .SH "COPYRIGHT"
 320 .IX Header "COPYRIGHT"
 321 Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
 322 .PP
 323 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 324 this file except in compliance with the License.  You can obtain a copy
 325 in the file \s-1LICENSE\s0 in the source distribution or at
 326 <https://www.openssl.org/source/license.html>.