Refine and re-wrap Min/Max protocol docs
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
This commit is contained in:
Viktor Dukhovni
parent
7946ab33ce
commit
57ce7b617c
4 changed files with 120 additions and 50 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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 v1, TLS v1.1 or TLS v1.2.
|
||||
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.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue