How are error codes structured

The main structure for error codes is documented in error.h.

Currently we try to keep all error codes within the negative space of 16 bit signed integers to support all 16-bit and 32-bit platforms (-0x0001 - -0x7FFF). In addition we'd like to give two layers of information on the error if possible. So in case an X.509 certificate is not parsed correctly because of an ASN.1 error, we would like to reflect that in the error code.

For that purpose we have divided the different modules into high-level modules and low-level modules. The low-level modules don't depend massively on something else, like the ASN.1 parser, the AES module, the SHA1 module or the OID database. The high-level modules are the ones that use low-level modules a lot, like the X.509 parser, the RSA module or the main SSL module.

For that purpose the 16-bit error codes are segmented in the following manner:

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

This space-division allows one error-code to propagate one low-level error and one high-level error in the same error code by just adding them together (HIGH_LEVEL_ERROR + LOW_LEVEL_ERROR). Warning: As the error codes are negative and processors use 2's complement internally for representing negative numbers, XOR'ing them together does NOT work!

As error codes are something 'internal', the actual representation and division is not relevant for high-level users that will only use the defined values anyway.

Adding a new low-level module to mbed TLS

Find some space within error.h to fit the number of error codes you need (Only 9 left at the time of writing). You can only use the even numbers in the space of 0x02 to 0x7E at this moment. You might have to move another module around.

Add the name to the list of low-level modules in error.h and in scripts/generate_errors.pl to the list of low-level modules.

Adding a new high-level module to mbed TLS

Find some module space in error.h to fit the number of error codes you need. As all the high-level module numbers are filled, we are now also starting to use the same numbers from the top.

Add the name to the list of high-level modules in error.h and in scripts/generate_errors.pl to the list of high-level modules.

User-friendly error strings for mbedtls_strerror()

Add the respective error codes to your module's header file with a description, like this:

#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */

The doxygen description will be used as the user-friendly mbedtls_strerror() error message.

Regenerate error.c

Now regenerate library/error.c with:

scripts/generate_errors.pl

Did this help?