Do not add error codes

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.

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.
+

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` |

drivers/builtin/include/mbedtls/error_common.h

@@ -11,97 +11,22 @@
 #define MBEDTLS_ERROR_COMMON_H
 
 #include "tf-psa-crypto/build_info.h"
-
+#include <psa/crypto_values.h>
 #include <stddef.h>
 
-/**
- * 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

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 <psa/crypto_types.h>
 
 /** \defgroup error Error codes
  * @{