Refine and re-wrap Min/Max protocol docs

Reviewed-by: N Viktor Dukhovni <viktor@openssl.org>

Refine and re-wrap Min/Max protocol docs
Reviewed-by: N Viktor Dukhovni <viktor@openssl.org>
57ce7b61 · Viktor Dukhovni · 7946ab33 · 57ce7b61 · 57ce7b61 · 57ce7b61
4 changed file
--- 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<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>,
+B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> 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<SSL_OP_NO_SSL3>,
-B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_2> respectively.
+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>

@@ -267,33 +273,44 @@ can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name

 This sets the minimum supported SSL, TLS or DTLS version.

-Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.

 =item B<MaxProtocol>

 This sets the maximum supported SSL, TLS or DTLS version.

-Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.

 =item B<Protocol>

-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<value> argument is a comma separated list of supported protocols to enable or disable.
+The B<value> 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<SSLv3>, B<TLSv1>, B<TLSv1.1>, B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
 The special value B<ALL> refers to all supported versions.

-This can't enable protocols that are disabled using B<MinProtocol> or B<MaxProtocol>, but can disable protocols that are still allowed by them.
+This can't enable protocols that are disabled using B<MinProtocol>
+or B<MaxProtocol>, but can disable protocols that are still allowed
+by them.

 The B<Protocol> command is fragile and deprecated; do not use it.
 Use B<MinProtocol> and B<MaxProtocol> instead.
-If you do use B<Protocol>, 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<Protocol>, 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<Options>

@@ -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_argv(3)>

 SSL_CONF_cmd() was first added to OpenSSL 1.0.2

-B<SSL_OP_NO_SSL2> doesn't have effect anymore since 1.1.0 but the define is kept
-for backward compatibility.
+B<SSL_OP_NO_SSL2> doesn't have effect since 1.1.0, but the macro is retained
+for backwards compatibility.

 B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of
 OpenSSL passing a command which didn't take an argument would return

--- 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<SSL_CTX> object as framework to establish TLS/SSL or DTLS enabled connections.
+SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
+establish TLS/SSL or DTLS enabled connections.

 =head1 NOTES

 The SSL_CTX object uses B<method> 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<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.
+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


--- 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<ctx> or B<ssl>.
-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<ctx> or B<ssl>.
+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<SSL3_VERSION>, B<TLS1_VERSION>, B<TLS1_1_VERSION>, B<TLS1_2_VERSION>, B<DTLS1_VERSION> and B<DTLS1_2_VERSION>.
+Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>,
+B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>,
+B<DTLS1_2_VERSION> 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


--- 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<SSL_CTX_set_min_proto_version(3)> and
+L<SSL_CTX_set_max_proto_version(3)> instead.

 =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION