Merge pull request #5972 from wernerlewis/migration_guide_removals
Add guidance for deprecated functions and macros to migration guide
diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
index 3653683..b933edf 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 @@
- 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 @@
`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 @@
### 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 @@
### 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 @@
### 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,
