From 745fcde406fbba9b7c3c7b54fc4186d4a36e3b15 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 23 Jun 2022 12:19:27 +0100 Subject: [PATCH 1/8] Add reference to 2.x docs to migration guide Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 3653683076..4a6c7ccf4f 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -13,7 +13,21 @@ 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. + + +## Referring to 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 in this guide. + +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 From 016cec17e87097c79b395a808aaafc23a0198eb3 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 23 Jun 2022 12:33:35 +0100 Subject: [PATCH 2/8] Add deprecated macros to migration guide Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 4a6c7ccf4f..71e5975728 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -262,12 +262,19 @@ 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 @@ -277,7 +284,7 @@ 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. From f8a478795cc3e9667b1b2ca15c173b410970223b Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Fri, 24 Jun 2022 11:02:54 +0100 Subject: [PATCH 3/8] Add guidance for generating deprecated list Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 71e5975728..e728446283 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -23,6 +23,10 @@ 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 in this guide. +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/development/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 From f5b86f3b16bae72467000ee4e63e38538d85f4ea Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Mon, 27 Jun 2022 09:20:01 +0100 Subject: [PATCH 4/8] Add clarification for 2.x section Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index e728446283..8474069037 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -15,8 +15,10 @@ The changes are detailed below, and include: - Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const. - 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. -## Referring to 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 From 4b8aaa4e60bc13786a6a6a76e62ade41c21f3722 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Mon, 27 Jun 2022 09:30:11 +0100 Subject: [PATCH 5/8] Add clarification on 2.x branch choice Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 8474069037..14c8aa821d 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -25,7 +25,8 @@ 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 in this guide. -To generate the documentation, checkout the `mbedtls-2.28` branch and follow +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/development/README.md#documentation). Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code. From 129d6adc0e397f6aedaa0b01c5df04ddd089de83 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Mon, 27 Jun 2022 09:41:28 +0100 Subject: [PATCH 6/8] Use mbedtls-2.28 branch for documentation link Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 14c8aa821d..86bf36e5e0 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -27,7 +27,7 @@ upgrade steps required will be explained 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/development/README.md#documentation). +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 From 4abd7c25457b96c2b815097652b6b936767504b6 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Mon, 27 Jun 2022 09:22:49 +0100 Subject: [PATCH 7/8] Minor phrasing changes Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 86bf36e5e0..5be42ea28a 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -23,7 +23,7 @@ Much of the information needed to determine a migration path can be found in the 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 in this guide. +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 @@ -284,7 +284,7 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f ### 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 @@ -362,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 From 05d5f81c204c0bd2157d8a9850aa21fa95552f61 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 29 Jun 2022 09:19:29 +0100 Subject: [PATCH 8/8] Fix spelling and formatting consistency Signed-off-by: Werner Lewis --- docs/3.0-migration-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 5be42ea28a..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 @@ -178,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. @@ -580,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,