From f6f7355e63bba7715f23721a9c6a35a9f8a75f1d Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 31 Jan 2025 20:08:17 +0100 Subject: [PATCH] Migration guide for error codes Signed-off-by: Gilles Peskine --- ChangeLog.d/error-unification.txt | 4 ++++ docs/4.0-migration-guide/error-codes.md | 26 +++++++++++++++++++++++++ 2 files changed, 30 insertions(+) create mode 100644 docs/4.0-migration-guide/error-codes.md diff --git a/ChangeLog.d/error-unification.txt b/ChangeLog.d/error-unification.txt index 0de1093dc..112ec8f5b 100644 --- a/ChangeLog.d/error-unification.txt +++ b/ChangeLog.d/error-unification.txt @@ -3,3 +3,7 @@ API changes functions can now return PSA_ERROR_xxx values. This will not affect most applications since the error values are between -32767 and -1 as before. + +Removals + * Remove many MBEDTLS_ERR_xxx error codes, superseded by PSA_ERROR_xxx. + See the 4.0 migration guide for details. diff --git a/docs/4.0-migration-guide/error-codes.md b/docs/4.0-migration-guide/error-codes.md new file mode 100644 index 000000000..9e338387c --- /dev/null +++ b/docs/4.0-migration-guide/error-codes.md @@ -0,0 +1,26 @@ +## Error codes + +### Unified error code space + +The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes. + +There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition. + +### Simplified legacy error codes + +All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code. + +Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable. + +As a consequence, the functions `mbedtls_low_level_sterr()` and `mbedtls_high_level_strerr()` no longer exist. + +### Removed error code names + +Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface. + +| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0, TF-PSA-Crypto 1.0) | +| ------------------------------ | ---------------------------------------------- | +| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` | +| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` | +| `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` | `PSA_ERROR_NOT_SUPPORTED` | +| `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` | `PSA_ERROR_HARDWARE_FAILURE` |