xref: /freebsd/secure/lib/libcrypto/man/man3/SSL_new.3 (revision e6bfd18d21b225af6a0ed67ceeaf1293b7b9eba5)
Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)

Standard preamble:
========================================================================
..
..
.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "SSL_NEW 3"
SSL_NEW 3 "2023-05-30" "1.1.1u" "OpenSSL"
For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
"NAME"
SSL_dup, SSL_new, SSL_up_ref - create an SSL structure for a connection
"SYNOPSIS"
Header "SYNOPSIS" .Vb 1 #include <openssl/ssl.h> \& SSL *SSL_dup(SSL *s); SSL *SSL_new(SSL_CTX *ctx); int SSL_up_ref(SSL *s); .Ve
"DESCRIPTION"
Header "DESCRIPTION" \fBSSL_new() creates a new \s-1SSL\s0 structure which is needed to hold the data for a \s-1TLS/SSL\s0 connection. The new structure inherits the settings of the underlying context ctx: connection method, options, verification settings, timeout settings. An \s-1SSL\s0 structure is reference counted. Creating an \s-1SSL\s0 structure for the first time increments the reference count. Freeing it (using SSL_free) decrements it. When the reference count drops to zero, any memory or resources allocated to the \s-1SSL\s0 structure are freed.

\fBSSL_up_ref() increments the reference count for an existing \s-1SSL\s0 structure.

The function SSL_dup() creates and returns a new \s-1SSL\s0 structure from the same \fB\s-1SSL_CTX\s0 that was used to create s. It additionally duplicates a subset of the settings in s into the new \s-1SSL\s0 object.

For SSL_dup() to work, the connection \s-1MUST\s0 be in its initial state and \s-1MUST NOT\s0 have yet started the \s-1SSL\s0 handshake. For connections that are not in their initial state SSL_dup() just increments an internal reference count and returns the same handle. It may be possible to use SSL_clear\|(3) to recycle an \s-1SSL\s0 handle that is not in its initial state for re-use, but this is best avoided. Instead, save and restore the session, if desired, and construct a fresh handle for each connection.

The subset of settings in s that are duplicated are:

"any session data if configured (including the session_id_context)" 4
Item "any session data if configured (including the session_id_context)"

0

"any tmp_dh settings set via SSL_set_tmp_dh\|(3), SSL_set_tmp_dh_callback\|(3), or SSL_set_dh_auto\|(3)" 4
Item "any tmp_dh settings set via SSL_set_tmp_dh, SSL_set_tmp_dh_callback, or SSL_set_dh_auto"
"any configured certificates, private keys or certificate chains" 4
Item "any configured certificates, private keys or certificate chains"
"any configured signature algorithms, or client signature algorithms" 4
Item "any configured signature algorithms, or client signature algorithms"
"any \s-1DANE\s0 settings" 4
Item "any DANE settings"
"any Options set via SSL_set_options\|(3)" 4
Item "any Options set via SSL_set_options"
"any Mode set via SSL_set_mode\|(3)" 4
Item "any Mode set via SSL_set_mode"
"any minimum or maximum protocol settings set via SSL_set_min_proto_version\|(3) or SSL_set_max_proto_version\|(3) (Note: Only from OpenSSL 1.1.1h and above)" 4
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)"
"any Verify mode, callback or depth set via SSL_set_verify\|(3) or SSL_set_verify_depth\|(3) or any configured X509 verification parameters" 4
Item "any Verify mode, callback or depth set via SSL_set_verify or SSL_set_verify_depth or any configured X509 verification parameters"
"any msg callback or info callback set via SSL_set_msg_callback\|(3) or SSL_set_info_callback\|(3)" 4
Item "any msg callback or info callback set via SSL_set_msg_callback or SSL_set_info_callback"
"any default password callback set via SSL_set_default_passwd_cb\|(3)" 4
Item "any default password callback set via SSL_set_default_passwd_cb"
"any session id generation callback set via SSL_set_generate_session_id\|(3)" 4
Item "any session id generation callback set via SSL_set_generate_session_id"
"any configured Cipher List" 4
Item "any configured Cipher List"
"initial accept (server) or connect (client) state" 4
Item "initial accept (server) or connect (client) state"
"the max cert list value set via SSL_set_max_cert_list\|(3)" 4
Item "the max cert list value set via SSL_set_max_cert_list"
"the read_ahead value set via SSL_set_read_ahead\|(3)" 4
Item "the read_ahead value set via SSL_set_read_ahead"
"application specific data set via SSL_set_ex_data\|(3)" 4
Item "application specific data set via SSL_set_ex_data"
"any \s-1CA\s0 list or client \s-1CA\s0 list set via SSL_set0_CA_list\|(3), SSL_set0_client_CA_list() or similar functions" 4
Item "any CA list or client CA list set via SSL_set0_CA_list, SSL_set0_client_CA_list() or similar functions"
"any security level settings or callbacks" 4
Item "any security level settings or callbacks"
"any configured serverinfo data" 4
Item "any configured serverinfo data"
"any configured \s-1PSK\s0 identity hint" 4
Item "any configured PSK identity hint"
"any configured custom extensions" 4
Item "any configured custom extensions"
"any client certificate types configured via SSL_set1_client_certificate_types" 4
Item "any client certificate types configured via SSL_set1_client_certificate_types"

"RETURN VALUES"
Header "RETURN VALUES" The following return values can occur:
"\s-1NULL\s0" 4
Item "NULL" The creation of a new \s-1SSL\s0 structure failed. Check the error stack to find out the reason.
"Pointer to an \s-1SSL\s0 structure" 4
Item "Pointer to an SSL structure" The return value points to an allocated \s-1SSL\s0 structure. .Sp \fBSSL_up_ref() returns 1 for success and 0 for failure.
"SEE ALSO"
Header "SEE ALSO" \fBSSL_free\|(3), SSL_clear\|(3), \fBSSL_CTX_set_options\|(3), \fBSSL_get_SSL_CTX\|(3), \fBssl\|(7)
"COPYRIGHT"
Header "COPYRIGHT" Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.