yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Move sub-sections to more appropriate places

Browse source 
Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
This commit is contained in:
Dave Rodgman 2021-06-30 14:17:03 +01:00
parent 4ea5643046
commit a3758208ae
1 changed files with 75 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
docs/3.0-migration-guide.md
View file

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