diff options
author | Viktor Dukhovni <openssl-users@dukhovni.org> | 2015-12-29 03:19:24 -0500 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-01-02 10:48:35 -0500 |
commit | 57ce7b617c602ae8513c22daa2bda31f179edb0f (patch) | |
tree | 3f417c63b1752fbfaf4628aebe4d4f32c26aa0f5 /doc | |
parent | 7946ab33cecce60afcc00afc8fc18f31f9e66bff (diff) |
Refine and re-wrap Min/Max protocol docs
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CONF_cmd.pod | 52 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 85 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_min_proto_version.pod | 22 | ||||
-rw-r--r-- | 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<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 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<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 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<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 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<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 |