diff options
Diffstat (limited to 'doc/ssl/SSL_CTX_new.pod')
| -rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 110 |
1 files changed, 56 insertions, 54 deletions
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 2590986..53c79ae 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -76,85 +76,88 @@ B<method> can be of the following types: =over 4 -=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() - -An SSL connection established with these methods will only understand -the SSLv3 protocol. -A client will send out a SSLv3 client hello messages and will -indicate that it supports SSLv3. -A server will only understand SSLv3 client hello message and only -support the SSLv3 protocol. - -=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() +=item TLS_method(), TLS_server_method(), TLS_client_method() -A TLS connection established with these methods will only understand -the TLS 1.0 protocol. +These are the general-purpose I<version-flexible> SSL/TLS methods. +The actual protocol version used will be negotiated to the highest version +mutually supported by the client and the server. +The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2. +Most applications should use these method, and avoid the version specific +methods described below. -=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() +=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() -A TLS connection established with these methods will only understand -the TLS 1.1 protocol. +Use of these functions is deprecated. They have been replaced with the above +TLS_method(), TLS_server_method() and TLS_client_method() respectively. New +code should use those functions instead. =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() -A TLS connection established with these methods will only understand -the TLS 1.2 protocol. +A TLS/SSL connection established with these methods will only understand the +TLSv1.2 protocol. -=item TLS_method(), TLS_server_method(), TLS_client_method() +=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() -A TLS/SSL connection established with these methods may understand -the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. +A TLS/SSL connection established with these methods will only understand the +TLSv1.1 protocol. -If extensions are required (for example server name) -a client will send out TLSv1 client hello messages including extensions and -will indicate that it also understands TLSv1.1, TLSv1.2 and permits a -fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 -protocols. This is the best choice when compatibility is a concern. +=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() -=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. -Use of these functions is deprecated. They have been replaced with TLS_method(), -TLS_server_method() and TLS_client_method() respectively. New code should use -those functions instead. +=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() + +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. +The SSLv3 protocol is deprecated and should not be used. =item DTLS_method(), DTLS_server_method(), DTLS_client_method() -A DTLS connection established with those methods understands all -supported DTLS protocols. +These are the version-flexible DTLS methods. Currently supported protocols are DTLS 1.0 and DTLS 1.2. -=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() +=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() -A DTLS connection established with these methods will only understand -the DTLS 1.0 protocol. +These are the version-specific methods for DTLSv1.2. -=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() +=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() -A DTLS connection established with these methods will only understand -the DTLS 1.2 protocol. +These are the version-specific methods for DTLSv1. =back +SSL_CTX_new() initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates and the options to their default values. + TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), -DTLS_server_method() and DTLS_client_method() are the version -flexible methods. +DTLS_server_method() and DTLS_client_method() are the I<version-flexible> +methods. All other methods only support one specific protocol version. -Use these methods instead of the other version specific methods. +Use the I<version-flexible> methods instead of the version specific methods. If you want to limit the supported protocols for the version flexible -methods you can use SSL_CTX_set_min_proto_version(), -SSL_set_min_proto_version(), SSL_CTX_set_max_proto_version() and -SSL_set_max_proto_version() functions. -They can also be limited by setting an option like B<SSL_OP_NO_SSLv3> -via the L<SSL_CTX_set_options(3)> or L<SSL_set_options(3)> functions, -but that's not recommended. +methods you can use L<SSL_CTX_set_min_proto_version(3)>, +L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and +LSSL_set_max_proto_version(3)> functions. Using these functions it is possible to choose e.g. TLS_server_method() and be able to negotiate with all possible clients, but to only allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2. -SSL_CTX_new() initializes the list of ciphers, the session cache -setting, the callbacks, the keys and certificates and the options -to its default values. +The list of protocols available can also be limited using the +B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and +B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or +L<SSL_set_options(3)> functions, but this approach is not recommended. +Clients should avoid creating "holes" in the set of protocols they support. +When disabling a protocol, make sure that you also disable either all previous +or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling I<all> +previous protocol versions, the effect is to also disable all subsequent +protocol versions. + +The SSLv3 protocol is deprecated and should generally not be used. +Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set +the minimum protocol to at least B<TLS1_VERSION>. =head1 RETURN VALUES @@ -164,8 +167,8 @@ The following return values can occur: =item NULL -The creation of a new SSL_CTX object failed. Check the error stack to -find out the reason. +The creation of a new SSL_CTX object failed. Check the error stack to find out +the reason. =item Pointer to an SSL_CTX object @@ -185,8 +188,7 @@ and TLS_client_method() functions were introduced in OpenSSL 1.1.0. =head1 SEE ALSO -L<SSL_CTX_free(3)>, L<SSL_accept(3)>, -L<SSL_CTX_set_min_proto_version(3)>, -L<ssl(3)>, L<SSL_set_connect_state(3)> +L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>, +L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)> =cut |