diff options
author | Kurt Roeckx <kurt@roeckx.be> | 2015-12-06 17:56:41 +0100 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-01-02 10:47:52 -0500 |
commit | 7946ab33cecce60afcc00afc8fc18f31f9e66bff (patch) | |
tree | fa178fbc42a649e87e201820cc11796dc3c7d6de /doc | |
parent | 1e0784ff95cd69090e26e2205bfec6305038db56 (diff) |
Add support for minimum and maximum protocol version
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CONF_cmd.pod | 73 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 126 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_min_proto_version.pod | 42 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_options.pod | 10 |
4 files changed, 186 insertions, 65 deletions
diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod index bebd20485c..cfac7e22d2 100644 --- a/doc/ssl/SSL_CONF_cmd.pod +++ b/doc/ssl/SSL_CONF_cmd.pod @@ -74,7 +74,7 @@ B<prime256v1>). Curve names are case sensitive. =item B<-named_curve> -This sets the temporary curve used for ephemeral ECDH modes. Only used by +This sets the temporary curve used for ephemeral ECDH modes. Only used by servers The B<value> argument is a curve name or the special value B<auto> which @@ -85,7 +85,7 @@ can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name =item B<-cipher> Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is -currently not performed unless a B<SSL> or B<SSL_CTX> structure is +currently not performed unless a B<SSL> or B<SSL_CTX> structure is associated with B<cctx>. =item B<-cert> @@ -109,9 +109,14 @@ Attempts to use the file B<value> as the set of temporary DH parameters for the appropriate context. This option is only supported if certificate 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>. + =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 +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. @@ -177,7 +182,7 @@ Note: the command prefix (if set) alters the recognised B<cmd> values. =item B<CipherString> Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is -currently not performed unless an B<SSL> or B<SSL_CTX> structure is +currently not performed unless an B<SSL> or B<SSL_CTX> structure is associated with B<cctx>. =item B<Certificate> @@ -250,7 +255,7 @@ B<prime256v1>). Curve names are case sensitive. =item B<ECDHParameters> -This sets the temporary curve used for ephemeral ECDH modes. Only used by +This sets the temporary curve used for ephemeral ECDH modes. Only used by servers The B<value> argument is a curve name or the special value B<Automatic> which @@ -258,16 +263,37 @@ picks an appropriate curve based on client and server preferences. The curve can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g B<prime256v1>). Curve names are case sensitive. +=item B<MinProtocol> + +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>. + +=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>. + =item B<Protocol> -The supported versions of the SSL or TLS 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. +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. + +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. -The B<value> argument is a comma separated list of supported protocols to -enable or disable. If an protocol is preceded by B<-> that version is disabled. -All versions are enabled by default, though applications may choose to -explicitly disable some. Currently supported protocol values are -B<SSLv3>, B<TLSv1>, B<TLSv1.1> and B<TLSv1.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. + +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. =item B<Options> @@ -404,7 +430,7 @@ can be checked instead. If -3 is returned a required argument is missing and an error is indicated. If 0 is returned some other error occurred and this can be reported back to the user. -The function SSL_CONF_cmd_value_type() can be used by applications to +The function SSL_CONF_cmd_value_type() can be used by applications to check for the existence of a command or to perform additional syntax checking or translation of the command value. For example if the return value is B<SSL_CONF_TYPE_FILE> an application could translate a relative @@ -416,12 +442,29 @@ Set supported signature algorithms: SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); -Enable all protocols except SSLv3: +There are various ways to select the supported procotols. + +This set the minimum protocol version to TLSv1, and so disables SSLv3. +This is the recommended way to disable protocols. + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); + +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. SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3"); Only enable TLSv1.2: + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); + SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); + +This also only enables TLSv1.2: + SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); Disable TLS session tickets: @@ -474,4 +517,6 @@ 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 B<SSL_CONF_TYPE_UNKNOWN>. +B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0. + =cut diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 15011f8fc1..2c2120a647 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -2,7 +2,7 @@ =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 - create a new SSL_CTX object as framework for TLS/SSL 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 @@ -10,51 +10,77 @@ SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_metho SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); + const SSL_METHOD *TLS_method(void); + const SSL_METHOD *TLS_server_method(void); + const SSL_METHOD *TLS_client_method(void); + + #define SSLv23_method TLS_method + #define SSLv23_server_method TLS_server_method + #define SSLv23_client_method TLS_client_method + + #ifndef OPENSSL_NO_SSL3_METHOD + const SSL_METHOD *SSLv3_method(void); + const SSL_METHOD *SSLv3_server_method(void); + const SSL_METHOD *SSLv3_client_method(void); + #endif + + const SSL_METHOD *TLSv1_method(void); + const SSL_METHOD *TLSv1_server_method(void); + const SSL_METHOD *TLSv1_client_method(void); + + const SSL_METHOD *TLSv1_1_method(void); + const SSL_METHOD *TLSv1_1_server_method(void); + const SSL_METHOD *TLSv1_1_client_method(void); + + const SSL_METHOD *TLSv1_2_method(void); + const SSL_METHOD *TLSv1_2_server_method(void); + const SSL_METHOD *TLSv1_2_client_method(void); + + const SSL_METHOD *DTLS_method(void); + const SSL_METHOD *DTLS_server_method(void); + const SSL_METHOD *DTLS_client_method(void); + + const SSL_METHOD *DTLSv1_method(void); + const SSL_METHOD *DTLSv1_server_method(void); + const SSL_METHOD *DTLSv1_client_method(void); + + const SSL_METHOD *DTLSv1_2_method(void); + const SSL_METHOD *DTLSv1_2_server_method(void); + const SSL_METHOD *DTLSv1_2_client_method(void); + =head1 DESCRIPTION -SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish -TLS/SSL 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. B<method> can be of the following types: +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. +B<method> can be of the following types: =over 4 -=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) +=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() -A TLS/SSL connection established with these methods will only understand the -SSLv3 protocol. A client will send out SSLv3 client hello messages -and will indicate that it only understands SSLv3. A server will only understand -SSLv3 client hello messages. +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(void), TLSv1_server_method(void), TLSv1_client_method(void) +=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1 protocol. A client will send out TLSv1 client hello messages -and will indicate that it only understands TLSv1. A server will only understand -TLSv1 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.0 protocol. -=item TLSv1_1_method(void), TLSv1_1_server_method(void), TLSv1_1_client_method(void) +=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages -and will indicate that it only understands TLSv1.1. A server will only -understand TLSv1.1 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.1 protocol. -=item TLSv1_2_method(void), TLSv1_2_server_method(void), TLSv1_2_client_method(void) +=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages -and will indicate that it only understands TLSv1.2. A server will only -understand TLSv1.2 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.2 protocol. -=item TLS_method(void), TLS_server_method(void), TLS_client_method(void) +=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 @@ -62,26 +88,36 @@ 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 SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) +=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() -Use of these functions is deprecated. They have been replaced with TLS_Method(), +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 DTLS_method(), DTLS_server_method(), DTLS_client_method() + +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. + +=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. + =back -The list of protocols available can later be limited using the -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 -options of the SSL_CTX_set_options() or SSL_set_options() functions. -Using these options 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 TLSv1, TLSv1.1 or TLS v1.2. +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. -Applications which never want to support SSLv3 can set SSL_OP_NO_SSLv3. +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. +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 @@ -102,14 +138,14 @@ The return value points to an allocated SSL_CTX object. =head1 HISTORY -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. +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. =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)> =cut diff --git a/doc/ssl/SSL_CTX_set_min_proto_version.pod b/doc/ssl/SSL_CTX_set_min_proto_version.pod new file mode 100644 index 0000000000..4cb4c43a2d --- /dev/null +++ b/doc/ssl/SSL_CTX_set_min_proto_version.pod @@ -0,0 +1,42 @@ +=pod + +=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 + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version); + int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version); + int SSL_set_min_proto_version(SSL *ssl, int version); + int SSL_set_max_proto_version(SSL *ssl, int version); + +=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. + +When setting the minimum or maximum version to 0 it will use the lowest or highest supported version, respectively, by the library. + +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>. + +=head1 RETURN VALUES + +The function returns 1 on success and 0 on failure. + +=head1 NOTES + +All these functions are implemented using macros. + +=head1 HISTORY + +The functions were added in OpenSSL 1.1.0 + +=head1 SEE ALSO + +L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod index cf137a5ed4..bf7f7fd318 100644 --- a/doc/ssl/SSL_CTX_set_options.pod +++ b/doc/ssl/SSL_CTX_set_options.pod @@ -153,13 +153,10 @@ own preferences. ... -=item SSL_OP_NO_SSLv3 +=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 -Do not use the SSLv3 protocol. - -=item SSL_OP_NO_TLSv1 - -Do not use the TLSv1 protocol. +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(). =item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION @@ -269,6 +266,7 @@ secure renegotiation and 0 if it does not. L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_min_proto_version(3)>, L<dhparam(1)> =head1 HISTORY |