secure/lib/libcrypto/man/man3/SSL_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   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_NEW 3"
 136 .TH SSL_NEW 3 "2020-09-22" "1.1.1h" "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 SSL_dup, SSL_new, SSL_up_ref \- create an SSL structure for a connection
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& SSL *SSL_dup(SSL *s);
 149 \& SSL *SSL_new(SSL_CTX *ctx);
 150 \& int SSL_up_ref(SSL *s);
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 \&\fBSSL_new()\fR creates a new \fB\s-1SSL\s0\fR structure which is needed to hold the
 155 data for a \s-1TLS/SSL\s0 connection. The new structure inherits the settings
 156 of the underlying context \fBctx\fR: connection method,
 157 options, verification settings, timeout settings. An \fB\s-1SSL\s0\fR structure is
 158 reference counted. Creating an \fB\s-1SSL\s0\fR structure for the first time increments
 159 the reference count. Freeing it (using SSL_free) decrements it. When the
 160 reference count drops to zero, any memory or resources allocated to the \fB\s-1SSL\s0\fR
 161 structure are freed.
 162 .PP
 163 \&\fBSSL_up_ref()\fR increments the reference count for an
 164 existing \fB\s-1SSL\s0\fR structure.
 165 .PP
 166 The function \fBSSL_dup()\fR creates and returns a new \fB\s-1SSL\s0\fR structure from the same
 167 \&\fB\s-1SSL_CTX\s0\fR that was used to create \fIs\fR. It additionally duplicates a subset of
 168 the settings in \fIs\fR into the new \fB\s-1SSL\s0\fR object.
 169 .PP
 170 For \fBSSL_dup()\fR to work, the connection \s-1MUST\s0 be in its initial state and
 171 \&\s-1MUST NOT\s0 have yet started the \s-1SSL\s0 handshake.  For connections that are not in
 172 their initial state \fBSSL_dup()\fR just increments an internal
 173 reference count and returns the \fIsame\fR handle.  It may be possible to
 174 use \fBSSL_clear\fR\|(3) to recycle an \s-1SSL\s0 handle that is not in its initial
 175 state for re-use, but this is best avoided.  Instead, save and restore
 176 the session, if desired, and construct a fresh handle for each connection.
 177 .PP
 178 The subset of settings in \fIs\fR that are duplicated are:
 179 .IP "any session data if configured (including the session_id_context)" 4
 180 .IX Item "any session data if configured (including the session_id_context)"
 181 .PD 0
 182 .IP "any tmp_dh settings set via \fBSSL_set_tmp_dh\fR\|(3), \fBSSL_set_tmp_dh_callback\fR\|(3), or \fBSSL_set_dh_auto\fR\|(3)" 4
 183 .IX Item "any tmp_dh settings set via SSL_set_tmp_dh, SSL_set_tmp_dh_callback, or SSL_set_dh_auto"
 184 .IP "any configured certificates, private keys or certificate chains" 4
 185 .IX Item "any configured certificates, private keys or certificate chains"
 186 .IP "any configured signature algorithms, or client signature algorithms" 4
 187 .IX Item "any configured signature algorithms, or client signature algorithms"
 188 .IP "any \s-1DANE\s0 settings" 4
 189 .IX Item "any DANE settings"
 190 .IP "any Options set via \fBSSL_set_options\fR\|(3)" 4
 191 .IX Item "any Options set via SSL_set_options"
 192 .IP "any Mode set via \fBSSL_set_mode\fR\|(3)" 4
 193 .IX Item "any Mode set via SSL_set_mode"
 194 .IP "any minimum or maximum protocol settings set via \fBSSL_set_min_proto_version\fR\|(3) or \fBSSL_set_max_proto_version\fR\|(3) (Note: Only from OpenSSL 1.1.1h and above)" 4
 195 .IX Item "any minimum or maximum protocol settings set via SSL_set_min_proto_version or SSL_set_max_proto_version (Note: Only from OpenSSL 1.1.1h and above)"
 196 .IP "any Verify mode, callback or depth set via \fBSSL_set_verify\fR\|(3) or \fBSSL_set_verify_depth\fR\|(3) or any configured X509 verification parameters" 4
 197 .IX Item "any Verify mode, callback or depth set via SSL_set_verify or SSL_set_verify_depth or any configured X509 verification parameters"
 198 .IP "any msg callback or info callback set via \fBSSL_set_msg_callback\fR\|(3) or \fBSSL_set_info_callback\fR\|(3)" 4
 199 .IX Item "any msg callback or info callback set via SSL_set_msg_callback or SSL_set_info_callback"
 200 .IP "any default password callback set via \fBSSL_set_default_passwd_cb\fR\|(3)" 4
 201 .IX Item "any default password callback set via SSL_set_default_passwd_cb"
 202 .IP "any session id generation callback set via \fBSSL_set_generate_session_id\fR\|(3)" 4
 203 .IX Item "any session id generation callback set via SSL_set_generate_session_id"
 204 .IP "any configured Cipher List" 4
 205 .IX Item "any configured Cipher List"
 206 .IP "initial accept (server) or connect (client) state" 4
 207 .IX Item "initial accept (server) or connect (client) state"
 208 .IP "the max cert list value set via \fBSSL_set_max_cert_list\fR\|(3)" 4
 209 .IX Item "the max cert list value set via SSL_set_max_cert_list"
 210 .IP "the read_ahead value set via \fBSSL_set_read_ahead\fR\|(3)" 4
 211 .IX Item "the read_ahead value set via SSL_set_read_ahead"
 212 .IP "application specific data set via \fBSSL_set_ex_data\fR\|(3)" 4
 213 .IX Item "application specific data set via SSL_set_ex_data"
 214 .IP "any \s-1CA\s0 list or client \s-1CA\s0 list set via \fBSSL_set0_CA_list\fR\|(3), \fBSSL_set0_client_CA_list()\fR or similar functions" 4
 215 .IX Item "any CA list or client CA list set via SSL_set0_CA_list, SSL_set0_client_CA_list() or similar functions"
 216 .IP "any security level settings or callbacks" 4
 217 .IX Item "any security level settings or callbacks"
 218 .IP "any configured serverinfo data" 4
 219 .IX Item "any configured serverinfo data"
 220 .IP "any configured \s-1PSK\s0 identity hint" 4
 221 .IX Item "any configured PSK identity hint"
 222 .IP "any configured custom extensions" 4
 223 .IX Item "any configured custom extensions"
 224 .IP "any client certificate types configured via SSL_set1_client_certificate_types" 4
 225 .IX Item "any client certificate types configured via SSL_set1_client_certificate_types"
 226 .PD
 227 .SH "RETURN VALUES"
 228 .IX Header "RETURN VALUES"
 229 The following return values can occur:
 230 .IP "\s-1NULL\s0" 4
 231 .IX Item "NULL"
 232 The creation of a new \s-1SSL\s0 structure failed. Check the error stack to
 233 find out the reason.
 234 .IP "Pointer to an \s-1SSL\s0 structure" 4
 235 .IX Item "Pointer to an SSL structure"
 236 The return value points to an allocated \s-1SSL\s0 structure.
 237 .Sp
 238 \&\fBSSL_up_ref()\fR returns 1 for success and 0 for failure.
 239 .SH "SEE ALSO"
 240 .IX Header "SEE ALSO"
 241 \&\fBSSL_free\fR\|(3), \fBSSL_clear\fR\|(3),
 242 \&\fBSSL_CTX_set_options\fR\|(3),
 243 \&\fBSSL_get_SSL_CTX\fR\|(3),
 244 \&\fBssl\fR\|(7)
 245 .SH "COPYRIGHT"
 246 .IX Header "COPYRIGHT"
 247 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
 248 .PP
 249 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 250 this file except in compliance with the License.  You can obtain a copy
 251 in the file \s-1LICENSE\s0 in the source distribution or at
 252 <https://www.openssl.org/source/license.html>.