doc/ssl/SSL_CTX_new.pod

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