diff --git a/ChangeLog.d/error-unification.txt b/ChangeLog.d/error-unification.txt new file mode 100644 index 000000000..112ec8f5b --- /dev/null +++ b/ChangeLog.d/error-unification.txt @@ -0,0 +1,9 @@ +API changes + * The PSA and Mbed TLS error spaces are now unified. mbedtls_xxx() + 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/README b/docs/4.0-migration-guide/README new file mode 100644 index 000000000..6122f5647 --- /dev/null +++ b/docs/4.0-migration-guide/README @@ -0,0 +1,22 @@ +This directory contains sections intended for the migration guide +from Mbed TLS 3.6 to TF-PSA-Crypto 1.0 + Mbed TLS 4.0. + +The files in this document should be markdown files with the .md +extension. They should generally contain level-2 sections (## title). +The files will be consolidated into a single cohesive document or +document set shortly before the .0 releases. + +The reason to have multiple files is that each strand of work can create +one file, without worrying about where to fit in the document structure. +We'll worry about the general structure once we have the content. +Furthermore, placing different strands of work in separate files will +avoid merge conflicts (as would happen e.g. if parallel strands of +work append to the same file in concurrent pull requests). + +Files can be placed in the docs/4.0-migration-guide indifferently in +mbedtls or TF-PSA-Crypto, as convenient. + +Documentation that is specifically about migrating from the legacy +crypto API to the PSA crypto API should be added to the existing +docs/psa-transition.md instead. + 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` | diff --git a/drivers/builtin/include/mbedtls/error_common.h b/drivers/builtin/include/mbedtls/error_common.h index 724da7aff..ef9fd6cc0 100644 --- a/drivers/builtin/include/mbedtls/error_common.h +++ b/drivers/builtin/include/mbedtls/error_common.h @@ -11,97 +11,22 @@ #define MBEDTLS_ERROR_COMMON_H #include "tf-psa-crypto/build_info.h" - +#include #include -/** - * Error code layout. - * - * Currently we try to keep all error codes within the negative space of 16 - * bits signed integers to support all platforms (-0x0001 - -0x7FFF). In - * addition we'd like to give two layers of information on the error if - * possible. - * - * For that purpose the error codes are segmented in the following manner: - * - * 16 bit error code bit-segmentation - * - * 1 bit - Unused (sign bit) - * 3 bits - High level module ID - * 5 bits - Module-dependent error code - * 7 bits - Low level module errors - * - * For historical reasons, low-level error codes are divided in even and odd, - * even codes were assigned first, and -1 is reserved for other errors. - * - * Low-level module errors (0x0002-0x007E, 0x0001-0x007F) - * - * Module Nr Codes assigned - * ERROR 2 0x006E 0x0001 - * MPI 7 0x0002-0x0010 - * GCM 3 0x0012-0x0016 0x0013-0x0013 - * THREADING 3 0x001A-0x001E - * AES 5 0x0020-0x0022 0x0021-0x0025 - * CAMELLIA 3 0x0024-0x0026 0x0027-0x0027 - * BASE64 2 0x002A-0x002C - * OID 1 0x002E-0x002E 0x000B-0x000B - * DES 2 0x0032-0x0032 0x0033-0x0033 - * CTR_DBRG 4 0x0034-0x003A - * ENTROPY 3 0x003C-0x0040 0x003D-0x003F - * NET 13 0x0042-0x0052 0x0043-0x0049 - * ARIA 4 0x0058-0x005E - * ASN1 7 0x0060-0x006C - * CMAC 1 0x007A-0x007A - * PBKDF2 1 0x007C-0x007C - * HMAC_DRBG 4 0x0003-0x0009 - * CCM 3 0x000D-0x0011 - * MD5 1 0x002F-0x002F - * RIPEMD160 1 0x0031-0x0031 - * SHA1 1 0x0035-0x0035 0x0073-0x0073 - * SHA256 1 0x0037-0x0037 0x0074-0x0074 - * SHA512 1 0x0039-0x0039 0x0075-0x0075 - * SHA-3 1 0x0076-0x0076 - * CHACHA20 3 0x0051-0x0055 - * POLY1305 3 0x0057-0x005B - * CHACHAPOLY 2 0x0054-0x0056 - * PLATFORM 2 0x0070-0x0072 - * LMS 5 0x0011-0x0019 - * - * High-level module nr (3 bits - 0x0...-0x7...) - * Name ID Nr of Errors - * PEM 1 9 - * PKCS#12 1 4 (Started from top) - * X509 2 20 - * PKCS5 2 4 (Started from top) - * DHM 3 11 - * PK 3 15 (Started from top) - * RSA 4 11 - * ECP 4 10 (Started from top) - * MD 5 5 - * HKDF 5 1 (Started from top) - * PKCS7 5 12 (Started from 0x5300) - * SSL 5 2 (Started from 0x5F00) - * CIPHER 6 8 (Started from 0x6080) - * SSL 6 22 (Started from top, plus 0x6000) - * SSL 7 20 (Started from 0x7000, gaps at - * 0x7380, 0x7900-0x7980, 0x7A80-0x7E80) - * - * Module dependent error code (5 bits 0x.00.-0x.F8.) - */ - #ifdef __cplusplus extern "C" { #endif -/** Generic error */ -#define MBEDTLS_ERR_ERROR_GENERIC_ERROR -0x0001 -/** This is a bug in the library */ -#define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E +/* Generic error */ +#define MBEDTLS_ERR_ERROR_GENERIC_ERROR PSA_ERROR_GENERIC_ERROR +/* This is a bug in the library */ +#define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED PSA_ERROR_CORRUPTION_DETECTED -/** Hardware accelerator failed */ -#define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED -0x0070 -/** The requested feature is not supported by the platform */ -#define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072 +/* Hardware accelerator failed */ +#define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED PSA_ERROR_HARDWARE_FAILURE +/* The requested feature is not supported by the platform */ +#define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED PSA_ERROR_NOT_SUPPORTED /** * \brief Combines a high-level and low-level error code together. @@ -130,13 +55,26 @@ extern void (*mbedtls_test_hook_error_add)(int, int, const char *, int); * error code (that denotes success) and can be combined with both a * negative error code or another value of zero. * + * \note The distinction between low-level and high-level error codes is + * obsolete since TF-PSA-Crypto 1.0 and Mbed TLS 4.0. It is still + * present in the code due to the heritage from Mbed TLS <=3, + * where low-level and high-level error codes could be added. + * New code should not make this distinction and should just + * propagate errors returned by lower-level modules unless there + * is a good reason to report a different error code in the + * higher-level module. + * * \note When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to * call \link mbedtls_test_hook_error_add \endlink. * - * \param high high-level error code. See error.h for more details. - * \param low low-level error code. See error.h for more details. - * \param file file where this error code addition occurred. - * \param line line where this error code addition occurred. + * \param high High-level error code, i.e. error code from the module + * that is reporting the error. + * This can be 0 to just propagate a low-level error. + * \param low Low-level error code, i.e. error code returned by + * a lower-level function. + * This can be 0 to just return a high-level error. + * \param file file where this error code combination occurred. + * \param line line where this error code combination occurred. */ static inline int mbedtls_error_add(int high, int low, const char *file, int line) @@ -149,7 +87,11 @@ static inline int mbedtls_error_add(int high, int low, (void) file; (void) line; - return high + low; + /* We give priority to the lower-level error code, because this + * is usually the right choice. For example, if a low-level module + * runs out of memory, this should not be converted to a high-level + * error code such as invalid-signature. */ + return low ? low : high; } #ifdef __cplusplus diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index ad4379760..2bbf1ddfb 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -27,6 +27,7 @@ #ifndef PSA_CRYPTO_VALUES_H #define PSA_CRYPTO_VALUES_H #include "mbedtls/private_access.h" +#include /** \defgroup error Error codes * @{