doc/man3/SSL_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_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
  17 SSL_new() creates a new B<SSL> structure which is needed to hold the
  18 data for a TLS/SSL connection. The new structure inherits the settings
  19 of the underlying context B<ctx>: connection method,
  20 options, verification settings, timeout settings. An B<SSL> structure is
  21 reference counted. Creating an B<SSL> structure for the first time increments
  22 the reference count. Freeing it (using SSL_free) decrements it. When the
  23 reference count drops to zero, any memory or resources allocated to the B<SSL>
  24 structure are freed.
  25
  26 SSL_up_ref() increments the reference count for an
  27 existing B<SSL> structure.
  28
  29 The function SSL_dup() creates and returns a new B<SSL> structure from the same
  30 B<SSL_CTX> that was used to create I<s>. It additionally duplicates a subset of
  31 the settings in I<s> into the new B<SSL> object.
  32
  33 For SSL_dup() to work, the connection MUST be in its initial state and
  34 MUST NOT have yet started the SSL handshake.  For connections that are not in
  35 their initial state SSL_dup() just increments an internal
  36 reference count and returns the I<same> handle.  It may be possible to
  37 use L<SSL_clear(3)> to recycle an SSL handle that is not in its initial
  38 state for reuse, but this is best avoided.  Instead, save and restore
  39 the session, if desired, and construct a fresh handle for each connection.
  40
  41 The 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)>,
  48 L<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
  61 L<SSL_set_min_proto_version(3)> or L<SSL_set_max_proto_version(3)> (Note: Only
  62 from OpenSSL 1.1.1h and above)
  63
  64 =item any verify mode, callback or depth set via L<SSL_set_verify(3)> or
  65 L<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
  68 L<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)>,
  85 SSL_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 SSL_dup() is not supported on QUIC SSL objects and returns NULL if called on
 100 such an object.
 101
 102 =head1 RETURN VALUES
 103
 104 The following return values can occur:
 105
 106 =over 4
 107
 108 =item NULL
 109
 110 The creation of a new SSL structure failed. Check the error stack to
 111 find out the reason.
 112
 113 =item Pointer to an SSL structure
 114
 115 The return value points to an allocated SSL structure.
 116
 117 SSL_up_ref() returns 1 for success and 0 for failure.
 118
 119 =back
 120
 121 =head1 SEE ALSO
 122
 123 L<SSL_free(3)>, L<SSL_clear(3)>,
 124 L<SSL_CTX_set_options(3)>,
 125 L<SSL_get_SSL_CTX(3)>,
 126 L<ssl(7)>
 127
 128 =head1 COPYRIGHT
 129
 130 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
 131
 132 Licensed under the Apache License 2.0 (the "License").  You may not use
 133 this file except in compliance with the License.  You can obtain a copy
 134 in the file LICENSE in the source distribution or at
 135 L<https://www.openssl.org/source/license.html>.
 136
 137 =cut