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 SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
  80
  81 An SSL connection established with these methods will only understand
  82 the SSLv3 protocol.
  83 A client will send out a SSLv3 client hello messages and will
  84 indicate that it supports SSLv3.
  85 A server will only understand SSLv3 client hello message and only
  86 support the SSLv3 protocol.
  87
  88 =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
  89
  90 A TLS connection established with these methods will only understand
  91 the TLS 1.0 protocol.
  92
  93 =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
  94
  95 A TLS connection established with these methods will only understand
  96 the TLS 1.1 protocol.
  97
  98 =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
  99
 100 A TLS connection established with these methods will only understand
 101 the TLS 1.2 protocol.
 102
 103 =item TLS_method(), TLS_server_method(), TLS_client_method()
 104
 105 A TLS/SSL connection established with these methods may understand
 106 the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
 107
 108 If extensions are required (for example server name)
 109 a client will send out TLSv1 client hello messages including extensions and
 110 will indicate that it also understands TLSv1.1, TLSv1.2 and permits a
 111 fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2
 112 protocols. This is the best choice when compatibility is a concern.
 113
 114 =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
 115
 116 Use of these functions is deprecated. They have been replaced with TLS_method(),
 117 TLS_server_method() and TLS_client_method() respectively. New code should use
 118 those functions instead.
 119
 120 =item DTLS_method(), DTLS_server_method(), DTLS_client_method()
 121
 122 A DTLS connection established with those methods understands all
 123 supported DTLS protocols.
 124 Currently supported protocols are DTLS 1.0 and DTLS 1.2.
 125
 126 =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
 127
 128 A DTLS connection established with these methods will only understand
 129 the DTLS 1.0 protocol.
 130
 131 =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
 132
 133 A DTLS connection established with these methods will only understand
 134 the DTLS 1.2 protocol.
 135
 136 =back
 137
 138 TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
 139 DTLS_server_method() and DTLS_client_method() are the version
 140 flexible methods.
 141 All other methods only support one specific protocol version.
 142 Use these methods instead of the other version specific methods.
 143
 144 If you want to limit the supported protocols for the version flexible
 145 methods you can use SSL_CTX_set_min_proto_version(),
 146 SSL_set_min_proto_version(), SSL_CTX_set_max_proto_version() and
 147 SSL_set_max_proto_version() functions.
 148 They can also be limited by setting an option like B<SSL_OP_NO_SSLv3>
 149 via the L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions,
 150 but that's not recommended.
 151 Using these functions it is possible to choose e.g. TLS_server_method()
 152 and be able to negotiate with all possible clients, but to only
 153 allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2.
 154
 155 SSL_CTX_new() initializes the list of ciphers, the session cache
 156 setting, the callbacks, the keys and certificates and the options
 157 to its default values.
 158
 159 =head1 RETURN VALUES
 160
 161 The following return values can occur:
 162
 163 =over 4
 164
 165 =item NULL
 166
 167 The creation of a new SSL_CTX object failed. Check the error stack to
 168 find out the reason.
 169
 170 =item Pointer to an SSL_CTX object
 171
 172 The return value points to an allocated SSL_CTX object.
 173
 174 =back
 175
 176 =head1 HISTORY
 177
 178 Support for SSLv2 and the corresponding SSLv2_method(),
 179 SSLv2_server_method() and SSLv2_client_method() functions where
 180 removed in OpenSSL 1.1.0.
 181
 182 SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
 183 were deprecated and the preferred TLS_method(), TLS_server_method()
 184 and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
 185
 186 =head1 SEE ALSO
 187
 188 L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
 189 L<SSL_CTX_set_min_proto_version(3)>,
 190 L<ssl(3)>,  L<SSL_set_connect_state(3)>
 191
 192 =cut