include/mbedtls/error.h

0001 /**
0002  * \file error.h
0003  *
0004  * \brief Error to string translation
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_ERROR_H
0011 #define MBEDTLS_ERROR_H
0012
0013 #include "mbedtls/build_info.h"
0014
0015 #include <stddef.h>
0016
0017 /**
0018  * Error code layout.
0019  *
0020  * Currently we try to keep all error codes within the negative space of 16
0021  * bits signed integers to support all platforms (-0x0001 - -0x7FFF). In
0022  * addition we'd like to give two layers of information on the error if
0023  * possible.
0024  *
0025  * For that purpose the error codes are segmented in the following manner:
0026  *
0027  * 16 bit error code bit-segmentation
0028  *
0029  * 1 bit  - Unused (sign bit)
0030  * 3 bits - High level module ID
0031  * 5 bits - Module-dependent error code
0032  * 7 bits - Low level module errors
0033  *
0034  * For historical reasons, low-level error codes are divided in even and odd,
0035  * even codes were assigned first, and -1 is reserved for other errors.
0036  *
0037  * Low-level module errors (0x0002-0x007E, 0x0001-0x007F)
0038  *
0039  * Module   Nr  Codes assigned
0040  * ERROR     2  0x006E          0x0001
0041  * MPI       7  0x0002-0x0010
0042  * GCM       3  0x0012-0x0016   0x0013-0x0013
0043  * THREADING 3  0x001A-0x001E
0044  * AES       5  0x0020-0x0022   0x0021-0x0025
0045  * CAMELLIA  3  0x0024-0x0026   0x0027-0x0027
0046  * BASE64    2  0x002A-0x002C
0047  * OID       1  0x002E-0x002E   0x000B-0x000B
0048  * PADLOCK   1  0x0030-0x0030
0049  * DES       2  0x0032-0x0032   0x0033-0x0033
0050  * CTR_DBRG  4  0x0034-0x003A
0051  * ENTROPY   3  0x003C-0x0040   0x003D-0x003F
0052  * NET      13  0x0042-0x0052   0x0043-0x0049
0053  * ARIA      4  0x0058-0x005E
0054  * ASN1      7  0x0060-0x006C
0055  * CMAC      1  0x007A-0x007A
0056  * PBKDF2    1  0x007C-0x007C
0057  * HMAC_DRBG 4                  0x0003-0x0009
0058  * CCM       3                  0x000D-0x0011
0059  * MD5       1                  0x002F-0x002F
0060  * RIPEMD160 1                  0x0031-0x0031
0061  * SHA1      1                  0x0035-0x0035 0x0073-0x0073
0062  * SHA256    1                  0x0037-0x0037 0x0074-0x0074
0063  * SHA512    1                  0x0039-0x0039 0x0075-0x0075
0064  * SHA-3     1                  0x0076-0x0076
0065  * CHACHA20  3                  0x0051-0x0055
0066  * POLY1305  3                  0x0057-0x005B
0067  * CHACHAPOLY 2 0x0054-0x0056
0068  * PLATFORM  2  0x0070-0x0072
0069  * LMS       5  0x0011-0x0019
0070  *
0071  * High-level module nr (3 bits - 0x0...-0x7...)
0072  * Name      ID  Nr of Errors
0073  * PEM       1   9
0074  * PKCS#12   1   4 (Started from top)
0075  * X509      2   20
0076  * PKCS5     2   4 (Started from top)
0077  * DHM       3   11
0078  * PK        3   15 (Started from top)
0079  * RSA       4   11
0080  * ECP       4   10 (Started from top)
0081  * MD        5   5
0082  * HKDF      5   1 (Started from top)
0083  * PKCS7     5   12 (Started from 0x5300)
0084  * SSL       5   2 (Started from 0x5F00)
0085  * CIPHER    6   8 (Started from 0x6080)
0086  * SSL       6   22 (Started from top, plus 0x6000)
0087  * SSL       7   20 (Started from 0x7000, gaps at
0088  *                   0x7380, 0x7900-0x7980, 0x7A80-0x7E80)
0089  *
0090  * Module dependent error code (5 bits 0x.00.-0x.F8.)
0091  */
0092
0093 #ifdef __cplusplus
0094 extern "C" {
0095 #endif
0096
0097 /** Generic error */
0098 #define MBEDTLS_ERR_ERROR_GENERIC_ERROR       -0x0001
0099 /** This is a bug in the library */
0100 #define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E
0101
0102 /** Hardware accelerator failed */
0103 #define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED     -0x0070
0104 /** The requested feature is not supported by the platform */
0105 #define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072
0106
0107 /**
0108  * \brief Combines a high-level and low-level error code together.
0109  *
0110  *        Wrapper macro for mbedtls_error_add(). See that function for
0111  *        more details.
0112  */
0113 #define MBEDTLS_ERROR_ADD(high, low) \
0114     mbedtls_error_add(high, low, __FILE__, __LINE__)
0115
0116 #if defined(MBEDTLS_TEST_HOOKS)
0117 /**
0118  * \brief Testing hook called before adding/combining two error codes together.
0119  *        Only used when invasive testing is enabled via MBEDTLS_TEST_HOOKS.
0120  */
0121 extern void (*mbedtls_test_hook_error_add)(int, int, const char *, int);
0122 #endif
0123
0124 /**
0125  * \brief Combines a high-level and low-level error code together.
0126  *
0127  *        This function can be called directly however it is usually
0128  *        called via the #MBEDTLS_ERROR_ADD macro.
0129  *
0130  *        While a value of zero is not a negative error code, it is still an
0131  *        error code (that denotes success) and can be combined with both a
0132  *        negative error code or another value of zero.
0133  *
0134  * \note  When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to
0135  *        call \link mbedtls_test_hook_error_add \endlink.
0136  *
0137  * \param high      high-level error code. See error.h for more details.
0138  * \param low       low-level error code. See error.h for more details.
0139  * \param file      file where this error code addition occurred.
0140  * \param line      line where this error code addition occurred.
0141  */
0142 static inline int mbedtls_error_add(int high, int low,
0143                                     const char *file, int line)
0144 {
0145 #if defined(MBEDTLS_TEST_HOOKS)
0146     if (*mbedtls_test_hook_error_add != NULL) {
0147         (*mbedtls_test_hook_error_add)(high, low, file, line);
0148     }
0149 #endif
0150     (void) file;
0151     (void) line;
0152
0153     return high + low;
0154 }
0155
0156 /**
0157  * \brief Translate an Mbed TLS error code into a string representation.
0158  *        The result is truncated if necessary and always includes a
0159  *        terminating null byte.
0160  *
0161  * \param errnum    error code
0162  * \param buffer    buffer to place representation in
0163  * \param buflen    length of the buffer
0164  */
0165 void mbedtls_strerror(int errnum, char *buffer, size_t buflen);
0166
0167 /**
0168  * \brief Translate the high-level part of an Mbed TLS error code into a string
0169  *        representation.
0170  *
0171  * This function returns a const pointer to an un-modifiable string. The caller
0172  * must not try to modify the string. It is intended to be used mostly for
0173  * logging purposes.
0174  *
0175  * \param error_code    error code
0176  *
0177  * \return The string representation of the error code, or \c NULL if the error
0178  *         code is unknown.
0179  */
0180 const char *mbedtls_high_level_strerr(int error_code);
0181
0182 /**
0183  * \brief Translate the low-level part of an Mbed TLS error code into a string
0184  *        representation.
0185  *
0186  * This function returns a const pointer to an un-modifiable string. The caller
0187  * must not try to modify the string. It is intended to be used mostly for
0188  * logging purposes.
0189  *
0190  * \param error_code    error code
0191  *
0192  * \return The string representation of the error code, or \c NULL if the error
0193  *         code is unknown.
0194  */
0195 const char *mbedtls_low_level_strerr(int error_code);
0196
0197 #ifdef __cplusplus
0198 }
0199 #endif
0200
0201 #endif /* error.h */