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 <Gilles.Peskine@arm.com>
diff --git a/docs/3.0-migration-guide.d/default-curves.md b/docs/3.0-migration-guide.d/default-curves.md
index 825609e..551e287 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 @@
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 a4a59b8..2ae74c9 100644
--- a/docs/3.0-migration-guide.md
+++ b/docs/3.0-migration-guide.md
@@ -65,31 +65,6 @@
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
----------------------------------------
