Re-order to put some more significant items at the top
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 402fc64..7874909 100644
--- a/docs/3.0-migration-guide.md
+++ b/docs/3.0-migration-guide.md
@@ -9,15 +9,85 @@
Here's the list of breaking changes; each entry should help you answer these
two questions: (1) am I affected? (2) if yes, what's my migration path?
-Some function parameters were made const
-----------------------------------------
+Introduce a level of indirection and versioning in the config files
+-------------------------------------------------------------------
-Various functions in the PK and ASN.1 modules had a `const` qualifier added to
-some of their parameters.
+`config.h` was split into `build_info.h` and `mbedtls_config.h`.
-This normally doesn't affect your code, unless you use pointers to reference
-those functions. In this case, you'll need to update the type of your pointers
-in order to match the new signature.
+* In code, use `#include <mbedtls/build_info.h>`. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`.
+* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before.
+* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros.
+
+Also, if you have a custom configuration file:
+
+* Don't include `check_config.h` or `config_psa.h` anymore.
+* Don't define `MBEDTLS_CONFIG_H` anymore.
+
+A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced.
+Defining it to a particular value will ensure that Mbed TLS interprets
+the config file in a way that's compatible with the config file format
+used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same
+value.
+The only value supported by Mbed TLS 3.0.0 is `0x03000000`.
+
+Remove suport for TLS 1.0, 1.1 and DTLS 1.0
+-------------------------------------------
+
+This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols.
+
+These versions have been deprecated by RFC 8996.
+Keeping them in the library creates opportunities for misconfiguration
+and possibly downgrade attacks. More generally, more code means a larger attack
+surface, even if the code is supposedly not used.
+
+The migration path is to adopt the latest versions of the protocol.
+
+As a consequence of removing TLS 1.0, support for CBC record splitting was
+also removed, as it was a work-around for a weakness in this particular
+version. There is no migration path since the feature is no longer relevant.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different version negociation mechanism), support
+for fallback SCSV (RFC 7507) was also removed. There is no migration path as
+it's no longer useful with TLS 1.2 and later.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different concept of ciphersuites), support for
+configuring ciphersuites separately for each version via
+`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use
+`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS
+1.2; in the future a different API will be added for (D)TLS 1.3.
+
+Remove support for SSL 3.0
+--------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3`
+and relied on that version in order to communicate with peers that are not up
+to date. If one of your peers is in that case, please try contacting them and
+encouraging them to upgrade their software.
+`0`.
+
+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.
Deprecated functions were removed from hashing modules
------------------------------------------------------
@@ -101,17 +171,6 @@
does, please try contacting them and encouraging them to upgrade their
software.
-Remove support for SSL 3.0
---------------------------
-
-This doesn't affect people using the default configuration as it was already
-disabled by default.
-
-This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3`
-and relied on that version in order to communicate with peers that are not up
-to date. If one of your peers is in that case, please try contacting them and
-encouraging them to upgrade their software.
-
Remove support for truncated HMAC
---------------------------------
@@ -252,25 +311,6 @@
The API is changed to include the parameter `critical` which allow to mark an
extension included in a CSR as critical. To get the previous behaviour pass
-`0`.
-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
-----------------------------------------------
@@ -711,33 +751,6 @@
If you are working with the pre-V3 certificates you need to switch to the
current ones.
-Remove suport for TLS 1.0, 1.1 and DTLS 1.0
--------------------------------------------
-
-This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols.
-
-These versions have been deprecated by RFC 8996.
-Keeping them in the library creates opportunities for misconfiguration
-and possibly downgrade attacks. More generally, more code means a larger attack
-surface, even if the code is supposedly not used.
-
-The migration path is to adopt the latest versions of the protocol.
-
-As a consequence of removing TLS 1.0, support for CBC record splitting was
-also removed, as it was a work-around for a weakness in this particular
-version. There is no migration path since the feature is no longer relevant.
-
-As a consequence of currently supporting only one version of (D)TLS (and in the
-future 1.3 which will have a different version negociation mechanism), support
-for fallback SCSV (RFC 7507) was also removed. There is no migration path as
-it's no longer useful with TLS 1.2 and later.
-
-As a consequence of currently supporting only one version of (D)TLS (and in the
-future 1.3 which will have a different concept of ciphersuites), support for
-configuring ciphersuites separately for each version via
-`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use
-`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS
-1.2; in the future a different API will be added for (D)TLS 1.3.
Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed
-----------------
@@ -881,26 +894,7 @@
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.
-Introduce a level of indirection and versioning in the config files
--------------------------------------------------------------------
-`config.h` was split into `build_info.h` and `mbedtls_config.h`.
-
-* In code, use `#include <mbedtls/build_info.h>`. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`.
-* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before.
-* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros.
-
-Also, if you have a custom configuration file:
-
-* Don't include `check_config.h` or `config_psa.h` anymore.
-* Don't define `MBEDTLS_CONFIG_H` anymore.
-
-A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced.
-Defining it to a particular value will ensure that Mbed TLS interprets
-the config file in a way that's compatible with the config file format
-used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same
-value.
-The only value supported by Mbed TLS 3.0.0 is `0x03000000`.
Removal of some SSL error codes
-----------------------------------------------------------------
@@ -971,3 +965,13 @@
e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)`
has the same effect as enabling the removed option. The default state is to use
the server order of suites.
+
+Some function parameters were made const
+----------------------------------------
+
+Various functions in the PK and ASN.1 modules had a `const` qualifier added to
+some of their parameters.
+
+This normally doesn't affect your code, unless you use pointers to reference
+those functions. In this case, you'll need to update the type of your pointers
+in order to match the new signature.
