From a3758208ae818233446c89132835ba74a2028c25 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:17:03 +0100 Subject: [PATCH] Move sub-sections to more appropriate places Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 151 ++++++++++++++++++------------------ 1 file changed, 75 insertions(+), 76 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index b9200ac09..182a3bca6 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -38,16 +38,6 @@ 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`. -### 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 @@ because the parameters concerned are usually constants in applications. 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 @@ and make sure your device is provisioned with a strong random seed. 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 @@ If no accessor function exists, please open an [enhancement request against Mbed 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 @@ removed from the library. Please use parameters from RFC3526 (still in the 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 @@ just use 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 @@ those functions. In this case, you'll need to update the type of your pointers in order to match the new signature. - ## PSA ### Deprecated names for PSA constants and types were removed @@ -522,24 +530,6 @@ implement those additional five API functions. ## 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 doesn't affect people using the default configuration. 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 @@ e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE 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.