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 reuse, 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 99SSL_dup() is not supported on QUIC SSL objects and returns NULL if called on 100such an object. 101 102=head1 RETURN VALUES 103 104The following return values can occur: 105 106=over 4 107 108=item NULL 109 110The creation of a new SSL structure failed. Check the error stack to 111find out the reason. 112 113=item Pointer to an SSL structure 114 115The return value points to an allocated SSL structure. 116 117SSL_up_ref() returns 1 for success and 0 for failure. 118 119=back 120 121=head1 SEE ALSO 122 123L<SSL_free(3)>, L<SSL_clear(3)>, 124L<SSL_CTX_set_options(3)>, 125L<SSL_get_SSL_CTX(3)>, 126L<ssl(7)> 127 128=head1 COPYRIGHT 129 130Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 131 132Licensed under the Apache License 2.0 (the "License"). You may not use 133this file except in compliance with the License. You can obtain a copy 134in the file LICENSE in the source distribution or at 135L<https://www.openssl.org/source/license.html>. 136 137=cut 138
