diff options
author | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-02-21 16:37:14 -0500 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-02-23 18:14:01 -0500 |
commit | 8c73aeb61e6df2bcd375532145fd7f97afbc3f11 (patch) | |
tree | 8194418e5e7a7bb75393af0bcc1857ee40de28b4 /doc/ssl | |
parent | 1cb7757ee7fde0ca19f64fd6f1886d4b41397b9c (diff) |
Update documentation of SSL METHODs and ciphers
Reviewed-by: Kurt Roeckx <kurt@openssl.org>
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CONF_cmd.pod | 6 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 110 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 58 |
3 files changed, 107 insertions, 67 deletions
diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod index 4f83f59967..17b8758605 100644 --- a/doc/ssl/SSL_CONF_cmd.pod +++ b/doc/ssl/SSL_CONF_cmd.pod @@ -122,9 +122,9 @@ than the deprecated alternative commands below. =item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> -Disables protocol support for SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2 -by setting the corresponding options B<SSL_OP_NO_SSL3>, B<SSL_OP_NO_TLS1>, -B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_2> respectively. +Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the +corresponding options B<SSL_OP_NO_SSL3>, B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> +and B<SSL_OP_NO_TLS1_2> respectively. These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>. =item B<-bugs> diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 259098657f..53c79ae6eb 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 diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index e350c3e14f..6bf731a871 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -118,29 +118,67 @@ protocol methods defined in B<SSL_METHOD> structures. =over 4 -=item const SSL_METHOD *B<SSLv3_client_method>(void); +=item const SSL_METHOD *B<TLS_method>(void); -Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. +Constructor for the I<version-flexible> SSL_METHOD structure for clients, +servers or both. +See L<SSL_CTX_new(3)> for details. -=item const SSL_METHOD *B<SSLv3_server_method>(void); +=item const SSL_METHOD *B<TLS_client_method>(void); -Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. +Constructor for the I<version-flexible> SSL_METHOD structure for clients. -=item const SSL_METHOD *B<SSLv3_method>(void); +=item const SSL_METHOD *B<TLS_server_method>(void); + +Constructor for the I<version-flexible> SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_2_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<TLSv1_2_client_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLSv1_2_server_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_1_method>(void); + +Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<TLSv1_1_client_method>(void); -Constructor for the SSLv3 SSL_METHOD structure for combined client and server. +Constructor for the TLSv1.1 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLSv1_1_server_method>(void); + +Constructor for the TLSv1.1 SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both. =item const SSL_METHOD *B<TLSv1_client_method>(void); -Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. +Constructor for the TLSv1 SSL_METHOD structure for clients. =item const SSL_METHOD *B<TLSv1_server_method>(void); -Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. +Constructor for the TLSv1 SSL_METHOD structure for servers. -=item const SSL_METHOD *B<TLSv1_method>(void); +=item const SSL_METHOD *B<SSLv3_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<SSLv3_client_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<SSLv3_server_method>(void); -Constructor for the TLSv1 SSL_METHOD structure for combined client and server. +Constructor for the SSLv3 SSL_METHOD structure for servers. =back |