Merge pull request #5972 from wernerlewis/migration_guide_removals

Add guidance for deprecated functions and macros to migration guide

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,