doc/man3/SSL_CTX_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
   6 SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method,
   7 SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method,
   8 TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
   9 TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method,
  10 SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method,
  11 DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method,
  12 DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method
  13 - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
  14 functions
  15
  16 =head1 SYNOPSIS
  17
  18  #include <openssl/ssl.h>
  19
  20  SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
  21  int SSL_CTX_up_ref(SSL_CTX *ctx);
  22
  23  const SSL_METHOD *TLS_method(void);
  24  const SSL_METHOD *TLS_server_method(void);
  25  const SSL_METHOD *TLS_client_method(void);
  26
  27  const SSL_METHOD *SSLv23_method(void);
  28  const SSL_METHOD *SSLv23_server_method(void);
  29  const SSL_METHOD *SSLv23_client_method(void);
  30
  31  #ifndef OPENSSL_NO_SSL3_METHOD
  32  const SSL_METHOD *SSLv3_method(void);
  33  const SSL_METHOD *SSLv3_server_method(void);
  34  const SSL_METHOD *SSLv3_client_method(void);
  35  #endif
  36
  37  #ifndef OPENSSL_NO_TLS1_METHOD
  38  const SSL_METHOD *TLSv1_method(void);
  39  const SSL_METHOD *TLSv1_server_method(void);
  40  const SSL_METHOD *TLSv1_client_method(void);
  41  #endif
  42
  43  #ifndef OPENSSL_NO_TLS1_1_METHOD
  44  const SSL_METHOD *TLSv1_1_method(void);
  45  const SSL_METHOD *TLSv1_1_server_method(void);
  46  const SSL_METHOD *TLSv1_1_client_method(void);
  47  #endif
  48
  49  #ifndef OPENSSL_NO_TLS1_2_METHOD
  50  const SSL_METHOD *TLSv1_2_method(void);
  51  const SSL_METHOD *TLSv1_2_server_method(void);
  52  const SSL_METHOD *TLSv1_2_client_method(void);
  53  #endif
  54
  55  const SSL_METHOD *DTLS_method(void);
  56  const SSL_METHOD *DTLS_server_method(void);
  57  const SSL_METHOD *DTLS_client_method(void);
  58
  59  #ifndef OPENSSL_NO_DTLS1_METHOD
  60  const SSL_METHOD *DTLSv1_method(void);
  61  const SSL_METHOD *DTLSv1_server_method(void);
  62  const SSL_METHOD *DTLSv1_client_method(void);
  63  #endif
  64
  65  #ifndef OPENSSL_NO_DTLS1_2_METHOD
  66  const SSL_METHOD *DTLSv1_2_method(void);
  67  const SSL_METHOD *DTLSv1_2_server_method(void);
  68  const SSL_METHOD *DTLSv1_2_client_method(void);
  69  #endif
  70
  71 =head1 DESCRIPTION
  72
  73 SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
  74 establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is
  75 reference counted. Creating an B<SSL_CTX> object for the first time increments
  76 the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
  77 reference count drops to zero, any memory or resources allocated to the
  78 B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for
  79 an existing B<SSL_CTX> structure.
  80
  81 =head1 NOTES
  82
  83 The SSL_CTX object uses B<method> as connection method.
  84 The methods exist in a generic type (for client and server use), a server only
  85 type, and a client only type.
  86 B<method> can be of the following types:
  87
  88 =over 4
  89
  90 =item TLS_method(), TLS_server_method(), TLS_client_method()
  91
  92 These are the general-purpose I<version-flexible> SSL/TLS methods.
  93 The actual protocol version used will be negotiated to the highest version
  94 mutually supported by the client and the server.
  95 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
  96 Applications should use these methods, and avoid the version-specific
  97 methods described below, which are deprecated.
  98
  99 =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
 100
 101 These functions do not exist anymore, they have been renamed to
 102 TLS_method(), TLS_server_method() and TLS_client_method() respectively.
 103 Currently, the old function calls are renamed to the corresponding new
 104 ones by preprocessor macros, to ensure that existing code which uses the
 105 old function names still compiles. However, using the old function names
 106 is deprecated and new code should call the new functions instead.
 107
 108 =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
 109
 110 A TLS/SSL connection established with these methods will only understand the
 111 TLSv1.2 protocol. These methods are deprecated.
 112
 113 =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
 114
 115 A TLS/SSL connection established with these methods will only understand the
 116 TLSv1.1 protocol.  These methods are deprecated.
 117
 118 =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
 119
 120 A TLS/SSL connection established with these methods will only understand the
 121 TLSv1 protocol. These methods are deprecated.
 122
 123 =item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
 124
 125 A TLS/SSL connection established with these methods will only understand the
 126 SSLv3 protocol.
 127 The SSLv3 protocol is deprecated and should not be used.
 128
 129 =item DTLS_method(), DTLS_server_method(), DTLS_client_method()
 130
 131 These are the version-flexible DTLS methods.
 132 Currently supported protocols are DTLS 1.0 and DTLS 1.2.
 133
 134 =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
 135
 136 These are the version-specific methods for DTLSv1.2.
 137 These methods are deprecated.
 138
 139 =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
 140
 141 These are the version-specific methods for DTLSv1.
 142 These methods are deprecated.
 143
 144 =back
 145
 146 SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
 147 callbacks, the keys and certificates and the options to their default values.
 148
 149 TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
 150 DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
 151 methods.
 152 All other methods only support one specific protocol version.
 153 Use the I<version-flexible> methods instead of the version specific methods.
 154
 155 If you want to limit the supported protocols for the version flexible
 156 methods you can use L<SSL_CTX_set_min_proto_version(3)>,
 157 L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
 158 L<SSL_set_max_proto_version(3)> functions.
 159 Using these functions it is possible to choose e.g. TLS_server_method()
 160 and be able to negotiate with all possible clients, but to only
 161 allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3.
 162
 163 The list of protocols available can also be limited using the
 164 B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>,
 165 B<SSL_OP_NO_TLSv1_3>, B<SSL_OP_NO_TLSv1_2> and B<SSL_OP_NO_TLSv1_3>
 166 options of the
 167 L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, but this approach
 168 is not recommended. Clients should avoid creating "holes" in the set of
 169 protocols they support. When disabling a protocol, make sure that you also
 170 disable either all previous or all subsequent protocol versions.
 171 In clients, when a protocol version is disabled without disabling I<all>
 172 previous protocol versions, the effect is to also disable all subsequent
 173 protocol versions.
 174
 175 The SSLv3 protocol is deprecated and should generally not be used.
 176 Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
 177 the minimum protocol to at least B<TLS1_VERSION>.
 178
 179 =head1 RETURN VALUES
 180
 181 The following return values can occur:
 182
 183 =over 4
 184
 185 =item NULL
 186
 187 The creation of a new SSL_CTX object failed. Check the error stack to find out
 188 the reason.
 189
 190 =item Pointer to an SSL_CTX object
 191
 192 The return value points to an allocated SSL_CTX object.
 193
 194 SSL_CTX_up_ref() returns 1 for success and 0 for failure.
 195
 196 =back
 197
 198 =head1 SEE ALSO
 199
 200 L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
 201 L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
 202
 203 =head1 HISTORY
 204
 205 Support for SSLv2 and the corresponding SSLv2_method(),
 206 SSLv2_server_method() and SSLv2_client_method() functions where
 207 removed in OpenSSL 1.1.0.
 208
 209 SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
 210 were deprecated and the preferred TLS_method(), TLS_server_method()
 211 and TLS_client_method() functions were added in OpenSSL 1.1.0.
 212
 213 All version-specific methods were deprecated in OpenSSL 1.1.0.
 214
 215 =head1 COPYRIGHT
 216
 217 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 218
 219 Licensed under the Apache License 2.0 (the "License").  You may not use
 220 this file except in compliance with the License.  You can obtain a copy
 221 in the file LICENSE in the source distribution or at
 222 L<https://www.openssl.org/source/license.html>.
 223
 224 =cut