From 3758fd6b79914d060124b5492da85a5693672bb5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 2 Jun 2021 00:07:17 +0200 Subject: [PATCH] Changelog entry and migration guide for hash and curve profile upgrades Signed-off-by: Gilles Peskine --- ChangeLog.d/default-curves.txt | 8 ++++++++ docs/3.0-migration-guide.d/default-curves.md | 16 ++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 ChangeLog.d/default-curves.txt create mode 100644 docs/3.0-migration-guide.d/default-curves.md diff --git a/ChangeLog.d/default-curves.txt b/ChangeLog.d/default-curves.txt new file mode 100644 index 000000000..1a805623d --- /dev/null +++ b/ChangeLog.d/default-curves.txt @@ -0,0 +1,8 @@ +Default behavior changes + * Some default policies for X.509 certificate verification and TLS have + changed: curves and hashes weaker than 255 bits are no longer accepted + by default. + +Removals + * Remove the compile-time option + MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE. diff --git a/docs/3.0-migration-guide.d/default-curves.md b/docs/3.0-migration-guide.d/default-curves.md new file mode 100644 index 000000000..5db517ebd --- /dev/null +++ b/docs/3.0-migration-guide.d/default-curves.md @@ -0,0 +1,16 @@ +Weak curves are now disabled by default for X.509 and TLS +--------------------------------------------------------- + +The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection have changed. X.509 and TLS now allow the same algorithms by default (except that the X.509 profile only lists curves that support signature verification). + +Hashes and curves weaker than 255 bits are no longer accepted by default. The following algorithms have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224, secp192r1, secp224r1, secp192k1, secp224k1 (weaker hashes were already not accepted). + +The compile-time option `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` is 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 you want. For example, to allow SHA-224: +``` +mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; +my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); +``` + +If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists.