From 7946ab33cecce60afcc00afc8fc18f31f9e66bff Mon Sep 17 00:00:00 2001 From: Kurt Roeckx Date: Sun, 6 Dec 2015 17:56:41 +0100 Subject: Add support for minimum and maximum protocol version Reviewed-by: Viktor Dukhovni --- doc/ssl/SSL_CONF_cmd.pod | 73 +++++++++++++---- doc/ssl/SSL_CTX_new.pod | 126 +++++++++++++++++++----------- doc/ssl/SSL_CTX_set_min_proto_version.pod | 42 ++++++++++ doc/ssl/SSL_CTX_set_options.pod | 10 +-- 4 files changed, 186 insertions(+), 65 deletions(-) create mode 100644 doc/ssl/SSL_CTX_set_min_proto_version.pod (limited to 'doc') 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). 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 argument is a curve name or the special value B which @@ -85,7 +85,7 @@ can be either the B name (e.g. B) or an OpenSSL OID name =item B<-cipher> Sets the cipher suite list to B. Note: syntax checking of B is -currently not performed unless a B or B structure is +currently not performed unless a B or B structure is associated with B. =item B<-cert> @@ -109,9 +109,14 @@ Attempts to use the file B 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, B, B, B, B and B. + =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, B, B and B respectively. @@ -177,7 +182,7 @@ Note: the command prefix (if set) alters the recognised B values. =item B Sets the cipher suite list to B. Note: syntax checking of B is -currently not performed unless an B or B structure is +currently not performed unless an B or B structure is associated with B. =item B @@ -250,7 +255,7 @@ B). Curve names are case sensitive. =item B -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 argument is a curve name or the special value B which @@ -258,16 +263,37 @@ picks an appropriate curve based on client and server preferences. The curve can be either the B name (e.g. B) or an OpenSSL OID name (e.g B). Curve names are case sensitive. +=item B + +This sets the minimum supported SSL, TLS or DTLS version. + +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. + =item B -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 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, B, B, B, B and B. +The special value B refers to all supported versions. -The B 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, 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. + +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. =item B @@ -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 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 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. +B and B 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 object as framework to establish -TLS/SSL 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. B can be of the following types: +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. +B 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, L, +L, L, L =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 + + 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 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. + +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, B, B, B, B and B. + +=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, L + +=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, L, L, L, +L, L =head1 HISTORY -- cgit v1.2.3