From cd5053465a272f842901f1f7bb8563d3cfae5b03 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 13 Mar 2025 15:52:00 +0000 Subject: [PATCH 1/3] Fix typos in the 3.0 migration guide Signed-off-by: David Horstmann --- 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 42af9dbaf2..a1747bcb4c 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -349,7 +349,7 @@ original names of those functions. The renamed functions are: | `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | | `mbedtls_sha512_ret` | `mbedtls_sha512` | -To migrate to the this change the user can keep the `*_ret` names in their code +To migrate to this change the user can keep the `*_ret` names in their code and include the `compat_2.x.h` header file which holds macros with proper renaming or to rename those functions in their code according to the list from mentioned header file. @@ -409,7 +409,7 @@ using the multi-part API. Previously, the documentation didn't state explicitly if it was OK to call `mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after the last call to `mbedtls_cipher_update()` — that is, without calling -`mbedtls_cipher_finish()` in-between. If you code was missing that call, +`mbedtls_cipher_finish()` in-between. If your code was missing that call, please add it and be prepared to get as much as 15 bytes of output. Currently the output is always 0 bytes, but it may be more when alternative @@ -422,7 +422,7 @@ This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. They are already niche or obsolete and most of them are weak or broken. For those reasons possible users should consider switching to modern and safe -alternatives to be found in literature. +alternatives to be found in the literature. ### Deprecated functions were removed from cipher @@ -806,11 +806,11 @@ multiple times on the same SSL configuration. In Mbed TLS 2.x, users would observe later calls overwriting the effect of earlier calls, with the prevailing PSK being the one that has been configured last. In Mbed TLS 3.0, -calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times +calling `mbedtls_ssl_conf_psk[_opaque]()` multiple times will return an error, leaving the first PSK intact. To achieve equivalent functionality when migrating to Mbed TLS 3.0, -users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should +users calling `mbedtls_ssl_conf_psk[_opaque]()` multiple times should remove all but the last call, so that only one call to _either_ `mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()` remains. From 235dfc2b8c92bab80c4c24ca8b767f760c42d488 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 13 Mar 2025 16:49:08 +0000 Subject: [PATCH 2/3] Add note about MBEDTLS_PRIVATE() in 3.6 Note that in the Mbed TLS 3.6 LTS, users can generally rely on being able to access struct members through the MBEDTLS_PRIVATE() macro, since we try to maintain ABI stability within an LTS version. Signed-off-by: David Horstmann --- 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 a1747bcb4c..02f5b49124 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -71,7 +71,7 @@ If you were accessing structure fields directly, and these fields are not docume If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). -As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. +As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. However, in the Mbed TLS 3.6 LTS this is generally a safe way to access struct members because LTS versions try to maintain ABI stability. ### Move part of timing module out of the library From 20220f09b42bd621592c46d180c59b4b89280ee4 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Fri, 14 Mar 2025 10:50:20 +0000 Subject: [PATCH 3/3] Reword slightly to be more tentative We don't guarantee ABI stability, but we do try to maintain it where we can. Signed-off-by: David Horstmann --- 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 02f5b49124..e927667b7e 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -71,7 +71,7 @@ If you were accessing structure fields directly, and these fields are not docume If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). -As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. However, in the Mbed TLS 3.6 LTS this is generally a safe way to access struct members because LTS versions try to maintain ABI stability. +As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. In the Mbed TLS 3.6 LTS this will tend to be safer than in a normal minor release because LTS versions try to maintain ABI stability. ### Move part of timing module out of the library