From edebcc04f8e7d5d3a084b6ee1bcd5cdbc4a8fd91 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 13 Mar 2025 15:52:00 +0000 Subject: [PATCH 1/4] 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 079d7909a1704b1a0a160dffcc4497deb648aea9 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 13 Mar 2025 16:49:08 +0000 Subject: [PATCH 2/4] 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 e35672940c4815fb8f011c7e4a7e40774a130f21 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Thu, 13 Mar 2025 16:53:27 +0000 Subject: [PATCH 3/4] Update broken link to PSA driver dev examples This link is broken in development as the document has been moved to the TF-PSA-Crypto repository. Signed-off-by: David Horstmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b00d21ae50..448f37294f 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,7 @@ However, it does not aim to implement the whole specification; in particular it Mbed TLS supports drivers for cryptographic accelerators, secure elements and random generators. This is work in progress. Please note that the driver interfaces are not fully stable yet and may change without notice. We intend to preserve backward compatibility for application code (using the PSA Crypto API), but the code of the drivers may have to change in future minor releases of Mbed TLS. -Please see the [PSA driver example and guide](docs/psa-driver-example-and-guide.md) for information on writing a driver. +Please see the [PSA driver example and guide](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-driver-example-and-guide.md) for information on writing a driver. License ------- From 1d181102fe88ba846ad22721c3f46c416c850489 Mon Sep 17 00:00:00 2001 From: David Horstmann Date: Fri, 14 Mar 2025 10:50:20 +0000 Subject: [PATCH 4/4] 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