From ec78bc47b53b290c0c833744671433cdd42be241 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 7 Jun 2021 21:11:27 +0200 Subject: [PATCH] Meld DEFAULT_ALLOW_SHA1_IN_CERTIFICATES removal migration guide Meld the migration guide for the removal of MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES into the migration guide for the strengthening of TLS and X.509 defaults, which is more general. The information in the SHA-1 section was largely already present in the strengthening section. It is now less straightforward to figure out how to enable SHA-1 in certificates, but that's a good thing, since no one should still be doing this in 2021. Signed-off-by: Gilles Peskine --- docs/3.0-migration-guide.d/default-curves.md | 2 +- docs/3.0-migration-guide.md | 25 -------------------- 2 files changed, 1 insertion(+), 26 deletions(-) diff --git a/docs/3.0-migration-guide.d/default-curves.md b/docs/3.0-migration-guide.d/default-curves.md index 825609e431..551e28721c 100644 --- a/docs/3.0-migration-guide.d/default-curves.md +++ b/docs/3.0-migration-guide.d/default-curves.md @@ -5,7 +5,7 @@ The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. -The compile-time option `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` is no longer available. +The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: ``` diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index a4a59b8895..2ae74c910d 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -65,31 +65,6 @@ If you're a library user and used to rely on having access to a structure or function that's now in a private header, please reach out on the mailing list and explain your need; we'll consider adding a new API in a future version. -Remove the option to allow SHA-1 by default in certificates ------------------------------------------------------------ - -This does not affect users who use the default `config.h`, as this option was -already off by default. - -If you used to enable `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` in your -`config.h`, first please take a moment to consider whether you really still -want to accept certificates signed with SHA-1 as those are considered insecure -and no CA has issued them for a while. If you really need to allow SHA-1 in -certificates, please set up a custom profile as follows: - -``` -const mbedtls_x509_crt_profile mbedtls_x509_crt_custom = { - MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA1 ) | - MBEDTLS_X509_ID_FLAG( /* other hash */ ) /* | etc */, - 0xFFFFFFF, /* Or specific PK algs */ - 0xFFFFFFF, /* Or specific curves */ - 2048 /* Or another RSA min bitlen */ -}; -``` -Then pass it to `mbedtls_x509_crt_verify_with_profile()` if you're verifying -a certificate chain directly, or to `mbedtls_ssl_conf_cert_profile()` if the -verification happens during a TLS handshake. - Remove the certs module from the library ----------------------------------------