diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 3653683076..b933edfe60 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -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,