1=pod 2 3=head1 NAME 4 5SSL_dup, SSL_new, SSL_up_ref - create an SSL structure for a connection 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 SSL *SSL_dup(SSL *s); 12 SSL *SSL_new(SSL_CTX *ctx); 13 int SSL_up_ref(SSL *s); 14 15=head1 DESCRIPTION 16 17SSL_new() creates a new B<SSL> structure which is needed to hold the 18data for a TLS/SSL connection. The new structure inherits the settings 19of the underlying context B<ctx>: connection method, 20options, verification settings, timeout settings. An B<SSL> structure is 21reference counted. Creating an B<SSL> structure for the first time increments 22the reference count. Freeing it (using SSL_free) decrements it. When the 23reference count drops to zero, any memory or resources allocated to the B<SSL> 24structure are freed. 25 26SSL_up_ref() increments the reference count for an 27existing B<SSL> structure. 28 29The function SSL_dup() creates and returns a new B<SSL> structure from the same 30B<SSL_CTX> that was used to create I<s>. It additionally duplicates a subset of 31the settings in I<s> into the new B<SSL> object. 32 33For SSL_dup() to work, the connection MUST be in its initial state and 34MUST NOT have yet started the SSL handshake. For connections that are not in 35their initial state SSL_dup() just increments an internal 36reference count and returns the I<same> handle. It may be possible to 37use L<SSL_clear(3)> to recycle an SSL handle that is not in its initial 38state for re-use, but this is best avoided. Instead, save and restore 39the session, if desired, and construct a fresh handle for each connection. 40 41The subset of settings in I<s> that are duplicated are: 42 43=over 4 44 45=item any session data if configured (including the session_id_context) 46 47=item any tmp_dh settings set via L<SSL_set_tmp_dh(3)>, 48L<SSL_set_tmp_dh_callback(3)>, or L<SSL_set_dh_auto(3)> 49 50=item any configured certificates, private keys or certificate chains 51 52=item any configured signature algorithms, or client signature algorithms 53 54=item any DANE settings 55 56=item any Options set via L<SSL_set_options(3)> 57 58=item any Mode set via L<SSL_set_mode(3)> 59 60=item any minimum or maximum protocol settings set via 61L<SSL_set_min_proto_version(3)> or L<SSL_set_max_proto_version(3)> (Note: Only 62from OpenSSL 1.1.1h and above) 63 64=item any Verify mode, callback or depth set via L<SSL_set_verify(3)> or 65L<SSL_set_verify_depth(3)> or any configured X509 verification parameters 66 67=item any msg callback or info callback set via L<SSL_set_msg_callback(3)> or 68L<SSL_set_info_callback(3)> 69 70=item any default password callback set via L<SSL_set_default_passwd_cb(3)> 71 72=item any session id generation callback set via L<SSL_set_generate_session_id(3)> 73 74=item any configured Cipher List 75 76=item initial accept (server) or connect (client) state 77 78=item the max cert list value set via L<SSL_set_max_cert_list(3)> 79 80=item the read_ahead value set via L<SSL_set_read_ahead(3)> 81 82=item application specific data set via L<SSL_set_ex_data(3)> 83 84=item any CA list or client CA list set via L<SSL_set0_CA_list(3)>, 85SSL_set0_client_CA_list() or similar functions 86 87=item any security level settings or callbacks 88 89=item any configured serverinfo data 90 91=item any configured PSK identity hint 92 93=item any configured custom extensions 94 95=item any client certificate types configured via SSL_set1_client_certificate_types 96 97=back 98 99=head1 RETURN VALUES 100 101The following return values can occur: 102 103=over 4 104 105=item NULL 106 107The creation of a new SSL structure failed. Check the error stack to 108find out the reason. 109 110=item Pointer to an SSL structure 111 112The return value points to an allocated SSL structure. 113 114SSL_up_ref() returns 1 for success and 0 for failure. 115 116=back 117 118=head1 SEE ALSO 119 120L<SSL_free(3)>, L<SSL_clear(3)>, 121L<SSL_CTX_set_options(3)>, 122L<SSL_get_SSL_CTX(3)>, 123L<ssl(7)> 124 125=head1 COPYRIGHT 126 127Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 128 129Licensed under the OpenSSL license (the "License"). You may not use 130this file except in compliance with the License. You can obtain a copy 131in the file LICENSE in the source distribution or at 132L<https://www.openssl.org/source/license.html>. 133 134=cut 135