Merge pull request #5972 from wernerlewis/migration_guide_removals
Add guidance for deprecated functions and macros to migration guide
This commit is contained in:
commit
7c6b0e4464
1 changed files with 38 additions and 10 deletions
|
@ -2,7 +2,7 @@
|
|||
|
||||
This guide details the steps required to migrate from Mbed TLS version 2.x to
|
||||
Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
|
||||
compatibility with previous versions, so users (and alt implementors) might
|
||||
compatibility with previous versions, so users (and alt implementers) might
|
||||
need to change their own code in order to make it work with Mbed TLS 3.0.
|
||||
|
||||
Here's the list of breaking changes; each entry should help you answer these
|
||||
|
@ -13,7 +13,28 @@ The changes are detailed below, and include:
|
|||
- Removal of many insecure or obsolete features
|
||||
- Tidying up of configuration options (including removing some less useful options).
|
||||
- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const.
|
||||
- Removal of functions previously marked as deprecated.
|
||||
- Removal of functions, macros, and types previously marked as deprecated.
|
||||
|
||||
Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation.
|
||||
|
||||
|
||||
## Accessing the Mbed TLS 2.x documentation
|
||||
|
||||
For features previously marked as deprecated, Mbed TLS 2.x documentation may
|
||||
explain how to upgrade, and should be referred to when migrating code. Where a
|
||||
migration path is not provided in prior documentation, changes made and the
|
||||
upgrade steps required will be explained later in this guide.
|
||||
|
||||
It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release.
|
||||
So to generate the documentation, checkout the `mbedtls-2.28` branch and follow
|
||||
the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation).
|
||||
Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code.
|
||||
|
||||
For some deprecated functions, 2.x documentation will suggest using a variant
|
||||
suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most
|
||||
of these variants have been renamed without the suffix. The section
|
||||
[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed)
|
||||
has further detail on which functions this applies to.
|
||||
|
||||
|
||||
## General changes
|
||||
|
@ -157,7 +178,7 @@ The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`,
|
|||
`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were
|
||||
removed. The primes from RFC 5114 are deprecated because their derivation is not
|
||||
documented and therefore their usage constitutes a security risk; they are fully
|
||||
removed from the library. Please use parameters from RFC3526 (still in the
|
||||
removed from the library. Please use parameters from RFC 3526 (still in the
|
||||
library, only in binary form) or RFC 7919 (also available in the library) or
|
||||
other trusted sources instead.
|
||||
|
||||
|
@ -248,22 +269,29 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f
|
|||
|
||||
### Deprecated error codes for hardware failures were removed
|
||||
|
||||
- The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules
|
||||
- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules
|
||||
were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
|
||||
instead.
|
||||
- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed;
|
||||
`MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead.
|
||||
- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
|
||||
were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
|
||||
|
||||
### Deprecated error codes for invalid input data were removed
|
||||
|
||||
- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia
|
||||
modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead.
|
||||
|
||||
### Remove the mode parameter from RSA functions
|
||||
|
||||
This affects all users who use the RSA encryption, decryption, sign and
|
||||
This affects all users who use the RSA encrypt, decrypt, sign and
|
||||
verify APIs.
|
||||
|
||||
The RSA module no longer supports private-key operations with the public key or
|
||||
vice versa. As a consequence, RSA operation functions no longer have a mode
|
||||
parameter. If you were calling RSA operations with the normal mode (public key
|
||||
for verification or encryption, private key for signature or decryption), remove
|
||||
the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling
|
||||
the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_PRIVATE` argument. If you were calling
|
||||
RSA operations with the wrong mode, which rarely makes sense from a security
|
||||
perspective, this is no longer supported.
|
||||
|
||||
|
@ -334,7 +362,7 @@ the RSA verify functions.
|
|||
|
||||
### Remove the padding parameters from `mbedtls_rsa_init()`
|
||||
|
||||
This affects all users who use the RSA encryption, decryption, sign and
|
||||
This affects all users who use the RSA encrypt, decrypt, sign and
|
||||
verify APIs.
|
||||
|
||||
The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1
|
||||
|
@ -552,13 +580,13 @@ extension if it contains any unsupported certificate policies.
|
|||
### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h`
|
||||
|
||||
This change affects users who have chosen the configuration options to disable the
|
||||
library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509
|
||||
library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
|
||||
certificates.
|
||||
|
||||
The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE`
|
||||
configuration options are removed and the X509 code now behaves as if they were
|
||||
configuration options are removed and the X.509 code now behaves as if they were
|
||||
always enabled. It is consequently not possible anymore to disable at compile
|
||||
time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509
|
||||
time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509
|
||||
certificates.
|
||||
|
||||
The verification of the `keyUsage` and `extendedKeyUsage` fields is important,
|
||||
|
|
Loading…
Reference in a new issue