Merge pull request #4604 from gilles-peskine-arm/default-hashes-curves-3.0

Update the default hash and curve selection for X.509 and TLS

docs/3.0-migration-guide.d/default-curves.md

@@ -0,0 +1,25 @@
+Strengthen default algorithm selection for X.509 and TLS
+--------------------------------------------------------
+
+The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification.
+
+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 options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available.
+
+The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing.
+
+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:
+```
+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.
+
+TLS now favors faster curves over larger curves
+-----------------------------------------------
+
+The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves.
+
+If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection.

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
 ----------------------------------------