From 57ce7b617c602ae8513c22daa2bda31f179edb0f Mon Sep 17 00:00:00 2001 From: Viktor Dukhovni Date: Tue, 29 Dec 2015 03:19:24 -0500 Subject: [PATCH] Refine and re-wrap Min/Max protocol docs Reviewed-by: Viktor Dukhovni --- doc/ssl/SSL_CONF_cmd.pod | 52 +++++++++----- doc/ssl/SSL_CTX_new.pod | 85 ++++++++++++++++------- doc/ssl/SSL_CTX_set_min_proto_version.pod | 22 ++++-- doc/ssl/SSL_CTX_set_options.pod | 15 ++-- 4 files changed, 122 insertions(+), 52 deletions(-) diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod index cfac7e22d2..2f708458e9 100644 --- a/doc/ssl/SSL_CONF_cmd.pod +++ b/doc/ssl/SSL_CONF_cmd.pod @@ -112,13 +112,19 @@ operations are permitted. =item B<-min_protocol>, B<-max_protocol> Sets the minimum and maximum supported protocol. -Currently supported protocol values are B, B, B, B, B and B. +Currently supported protocol values are B, B, +B, B for TLS and B, B for DTLS. +If the either bound is not specified then only the other bound applies, +if specified. +To restrict the supported protocol versions use these commands rather +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, -B, B and B respectively. +by setting the corresponding options B, B, +B and B respectively. +These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>. =item B<-bugs> @@ -267,33 +273,44 @@ can be either the B name (e.g. B) or an OpenSSL OID name This sets the minimum supported SSL, TLS or DTLS version. -Currently supported protocol values are B, B, B, B, B and B. +Currently supported protocol values are B, B, B, +B, B and B. =item B This sets the maximum supported SSL, TLS or DTLS version. -Currently supported protocol values are B, B, B, B, B and B. +Currently supported protocol values are B, B, B, +B, B and B. =item B -This can be used to enable or disable certain versions of the SSL, TLS or DTLS protocol. +This can be used to enable or disable certain versions of the SSL, +TLS or DTLS protocol. -The B argument is a comma separated list of supported protocols to enable or disable. +The B argument is a comma separated list of supported protocols +to enable or disable. If a protocol is preceded by B<-> that version is disabled. All protocol versions are enabled by default. -You need to disable at least 1 protocol version for this setting have any effect. -Only enabling some protocol versions does not disable the other protocol versions. +You need to disable at least one protocol version for this setting have any +effect. +Only enabling some protocol versions does not disable the other protocol +versions. -Currently supported protocol values are B, B, B, B, B and B. +Currently supported protocol values are B, B, B, +B, B and B. The special value B refers to all supported versions. -This can't enable protocols that are disabled using B or B, but can disable protocols that are still allowed by them. +This can't enable protocols that are disabled using B +or B, but can disable protocols that are still allowed +by them. The B command is fragile and deprecated; do not use it. Use B and B instead. -If you do use B, make sure that the resulting range of enabled protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make sure to also leave TLS 1.1 enabled. +If you do use B, make sure that the resulting range of enabled +protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make +sure to also leave TLS 1.1 enabled. =item B @@ -453,8 +470,11 @@ The following also disables SSLv3: SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); -The following will first enable all protocols, and then disable SSLv3. -If nothing was disabled before it has the same effect as "-SSLv3", but if things were disables it will first enable them again before disabling SSLv3. +The following will first enable all protocols, and then disable +SSLv3. +If no protocol versions were disabled before this has the same effect as +"-SSLv3", but if some versions were disables this will re-enable them before +disabling SSLv3. SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3"); @@ -510,8 +530,8 @@ L SSL_CONF_cmd() was first added to OpenSSL 1.0.2 -B doesn't have effect anymore since 1.1.0 but the define is kept -for backward compatibility. +B doesn't have effect since 1.1.0, but the macro is retained +for backwards compatibility. B was first added to OpenSSL 1.1.0. In earlier versions of OpenSSL passing a command which didn't take an argument would return diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 2c2120a647..136f97b366 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -2,7 +2,15 @@ =head1 NAME -SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled functions +SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, +TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, +TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, +TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, +SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, +DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, +DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method - +create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled +functions =head1 SYNOPSIS @@ -50,37 +58,46 @@ SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_metho =head1 DESCRIPTION -SSL_CTX_new() creates a new B object as framework to establish TLS/SSL or DTLS enabled connections. +SSL_CTX_new() creates a new B object as framework to +establish TLS/SSL or DTLS enabled connections. =head1 NOTES The SSL_CTX object uses B as connection method. -The methods exist in a generic type (for client and server use), a server only type, and a client only type. +The methods exist in a generic type (for client and server use), a server only +type, and a client only type. B 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. +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() -A TLS connection established with these methods will only understand the TLS 1.0 protocol. +A TLS connection established with these methods will only understand +the TLS 1.0 protocol. =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() -A TLS connection established with these methods will only understand the TLS 1.1 protocol. +A TLS connection established with these methods will only understand +the TLS 1.1 protocol. =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 connection established with these methods will only understand +the TLS 1.2 protocol. =item TLS_method(), TLS_server_method(), TLS_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 may understand +the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. If extensions are required (for example server name) a client will send out TLSv1 client hello messages including extensions and @@ -96,28 +113,42 @@ those functions instead. =item DTLS_method(), DTLS_server_method(), DTLS_client_method() -A DTLS connection established with those methods understands all supported DTLS protocols. +A DTLS connection established with those methods understands all +supported DTLS protocols. Currently supported protocols are DTLS 1.0 and DTLS 1.2. =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() -A DTLS connection established with these methods will only understand the DTLS 1.0 protocol. +A DTLS connection established with these methods will only understand +the DTLS 1.0 protocol. =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.2 protocol. +A DTLS connection established with these methods will only understand +the DTLS 1.2 protocol. =back -TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), DTLS_server_method() and DTLS_client_method() are the version flexible methods. -All other methods only support 1 specific protocol version. -It's recommended to use those 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 using by using an option like SSL_OP_NO_SSLv3 of the SSL_CTX_set_options() or SSL_set_options() functions, but that's not recommended. -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 v1, TLS v1.1 or TLS v1.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. +TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), +DTLS_server_method() and DTLS_client_method() are the version +flexible methods. +All other methods only support one specific protocol version. +Use these methods instead of the other 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 using by using an option like SSL_OP_NO_SSLv3 +of the SSL_CTX_set_options() or SSL_set_options() functions, but +that's not recommended. +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. =head1 RETURN VALUES @@ -138,9 +169,13 @@ The return value points to an allocated SSL_CTX object. =head1 HISTORY -SSLv3 -SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in OpenSSL 1.1.0. -SSLv23_method, SSLv23_server_method and SSLv23_client_method were deprecated and TLS_method, TLS_server_method and TLS_client_method were introduced in OpenSSL 1.1.0. +Support for SSLv2 and the corresponding SSLv2_method(), +SSLv2_server_method() and SSLv2_client_method() functions where +removed in OpenSSL 1.1.0. + +SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() +were deprecated and the preferred TLS_method(), TLS_server_method() +and TLS_client_method() functions were introduced in OpenSSL 1.1.0. =head1 SEE ALSO diff --git a/doc/ssl/SSL_CTX_set_min_proto_version.pod b/doc/ssl/SSL_CTX_set_min_proto_version.pod index 4cb4c43a2d..25f9cca23d 100644 --- a/doc/ssl/SSL_CTX_set_min_proto_version.pod +++ b/doc/ssl/SSL_CTX_set_min_proto_version.pod @@ -2,7 +2,9 @@ =head1 NAME -SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum and maximum supported protocol version +SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, +SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum +and maximum supported protocol version =head1 SYNOPSIS @@ -15,17 +17,23 @@ SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, SSL_set_min_proto_ =head1 DESCRIPTION -The functions set the minimum and maximum supported portocol versions for the B or B. -This works in combination with the options set via SSL_CTX_set_options() that allows to disable specific protocol versions. -You should use these functions instead of disabling a specific protocol version. +The functions set the minimum and maximum supported portocol versions +for the B or B. +This works in combination with the options set via SSL_CTX_set_options() +that also make it possible to disable specific protocol versions. +Use these functions instead of disabling specific protocol versions. -When setting the minimum or maximum version to 0 it will use the lowest or highest supported version, respectively, by the library. +Setting the minimum or maximum version to 0, will enable protocol +versions down to the lowest version, or up to the highest version +supported by the library, respectively. -Currently supported versions are B, B, B, B, B and B. +Currently supported versions are B, B, +B, B for TLS and B, +B for DTLS. =head1 RETURN VALUES -The function returns 1 on success and 0 on failure. +Both functions return 1 on success and 0 on failure. =head1 NOTES diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index bf7f7fd318..56f62cc59f 100644 --- a/doc/ssl/SSL_CTX_set_options.pod +++ b/doc/ssl/SSL_CTX_set_options.pod @@ -2,7 +2,9 @@ =head1 NAME -SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - manipulate SSL options +SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, +SSL_clear_options, SSL_CTX_get_options, SSL_get_options, +SSL_get_secure_renegotiation_support - manipulate SSL options =head1 SYNOPSIS @@ -153,10 +155,15 @@ own preferences. ... -=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 +=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, +SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2 -Do not use the SSLv3 or TLSv1 protocol, respectively. -You should avoid using those settings and instead use SSL_CTX_set_min_proto_version() and SSL_CTX_set_max_proto_version(). +These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol +versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS, +respectively. +As of OpenSSL 1.1.0, these options are deprecated, use +L and +L instead. =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION -- 2.25.1