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