Move sub-sections to more appropriate places
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
index b9200ac..182a3bc 100644
--- a/docs/3.0-migration-guide.md
+++ b/docs/3.0-migration-guide.md
@@ -38,16 +38,6 @@
value.
The only value supported by Mbed TLS 3.0.0 is `0x03000000`.
-### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior
-
-The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does
-not increase peak RAM usage anymore.
-
-If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM`
-to `0` in your config file. The impact depends on the number and size of
-enabled curves. For example, for P-256 the difference is 1KB; see the documentation
-of this option for details.
-
### Move part of timing module out of the library
The change affects users who use any of the following functions:
@@ -95,29 +85,6 @@
For more information see issue #4313.
-### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C`
-
-This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C
-was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are
-enabled.
-
-If you were using custom config file with MBEDTLS_SHA256_C enabled, then
-you will need to add `#define MBEDTLS_SHA224_C` option to your config.
-Current version of the library does not support enabling MBEDTLS_SHA256_C
-without MBEDTLS_SHA224_C.
-
-### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C`
-
-This does not affect users who use the default `mbedtls_config.h`.
-MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is
-enabled by default.
-
-If you were using a config file with both MBEDTLS_SHA512_C and
-MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384.
-If you were using a config file with MBEDTLS_SHA512_C and without
-MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add
-`#define MBEDTLS_SHA384_C` to your config file.
-
### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option
This does not affect users who use the default `mbedtls_config.h`, as this option was
@@ -129,14 +96,6 @@
Alternatively, for testing purposes only, you can create and register a fake
entropy function.
-### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed
-
-This doesn't affect users of the default configuration; it only affects people
-who were explicitly setting this option.
-
-This was a trade-off between code size and countermeasures; it is no longer
-relevant as the countermeasure is now always on at no cost in code size.
-
### Remove the HAVEGE module
This doesn't affect people using the default configuration as it was already
@@ -164,6 +123,14 @@
As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS.
+### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0
+
+This only affects people who've been using Mbed TLS since before version 2.0
+and still relied on `compat-1.3.h` in their code.
+
+Please use the new names directly in your code; `scripts/rename.pl` (from any
+of the 2.x releases — no longer included in 3.0) might help you do that.
+
## Low-level crypto
@@ -221,6 +188,56 @@
library, only in binary form) or RFC 7919 (also available in the library) or
other trusted sources instead.
+### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior
+
+The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does
+not increase peak RAM usage anymore.
+
+If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM`
+to `0` in your config file. The impact depends on the number and size of
+enabled curves. For example, for P-256 the difference is 1KB; see the documentation
+of this option for details.
+
+### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C`
+
+This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C
+was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are
+enabled.
+
+If you were using custom config file with MBEDTLS_SHA256_C enabled, then
+you will need to add `#define MBEDTLS_SHA224_C` option to your config.
+Current version of the library does not support enabling MBEDTLS_SHA256_C
+without MBEDTLS_SHA224_C.
+
+### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C`
+
+This does not affect users who use the default `mbedtls_config.h`.
+MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is
+enabled by default.
+
+If you were using a config file with both MBEDTLS_SHA512_C and
+MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384.
+If you were using a config file with MBEDTLS_SHA512_C and without
+MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add
+`#define MBEDTLS_SHA384_C` to your config file.
+
+### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed
+
+This doesn't affect users of the default configuration; it only affects people
+who were explicitly setting this option.
+
+This was a trade-off between code size and countermeasures; it is no longer
+relevant as the countermeasure is now always on at no cost in code size.
+
+### SHA-512 and SHA-256 output type change
+
+The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer.
+
+This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer.
+
+Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly.
+
+
## High-level crypto
### Remove wrapper for libpkcs11-helper
@@ -464,14 +481,6 @@
mbedtls_rsa_init(ctx);
```
-### SHA-512 and SHA-256 output type change
-
-The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer.
-
-This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer.
-
-Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly.
-
### Some function parameters were made const
Various functions in the PK and ASN.1 modules had a `const` qualifier added to
@@ -482,7 +491,6 @@
in order to match the new signature.
-
## PSA
### Deprecated names for PSA constants and types were removed
@@ -522,24 +530,6 @@
## X.509
-### 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.
-
### Remove the certs module from the library
This should not affect production use of the library, as the certificates and
@@ -715,14 +705,6 @@
This option has not had any effect for a long time. Please use the `lifetime`
parameter of `mbedtls_ssl_ticket_setup()` instead.
-### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0
-
-This only affects people who've been using Mbed TLS since before version 2.0
-and still relied on `compat-1.3.h` in their code.
-
-Please use the new names directly in your code; `scripts/rename.pl` (from any
-of the 2.x releases — no longer included in 3.0) might help you do that.
-
### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options
This change affects users who modified the default `mbedtls_config.h` padding granularity
@@ -1009,3 +991,20 @@
has the same effect as enabling the removed option. The default state is to use
the server order of suites.
+### 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.
