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