/work/mbedtls-3.6.6/include/mbedtls/error.h

Source
/**
 * \file error.h
 *
 * \brief Error to string translation
 */
/*
 *  Copyright The Mbed TLS Contributors
 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 */
#ifndef MBEDTLS_ERROR_H
#define MBEDTLS_ERROR_H

#include "mbedtls/build_info.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
 * PADLOCK   1  0x0030-0x0030
 * 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   3 (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

/** 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

/**
 * \brief Combines a high-level and low-level error code together.
 *
 *        Wrapper macro for mbedtls_error_add(). See that function for
 *        more details.
 */
#define MBEDTLS_ERROR_ADD(high, low) \
    mbedtls_error_add(high, low, __FILE__, __LINE__)

#if defined(MBEDTLS_TEST_HOOKS)
/**
 * \brief Testing hook called before adding/combining two error codes together.
 *        Only used when invasive testing is enabled via MBEDTLS_TEST_HOOKS.
 */
extern void (*mbedtls_test_hook_error_add)(int, int, const char *, int);
#endif

/**
 * \brief Combines a high-level and low-level error code together.
 *
 *        This function can be called directly however it is usually
 *        called via the #MBEDTLS_ERROR_ADD macro.
 *
 *        While a value of zero is not a negative error code, it is still an
 *        error code (that denotes success) and can be combined with both a
 *        negative error code or another value of zero.
 *
 * \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.
 */
static inline int mbedtls_error_add(int high, int low,
                                    const char *file, int line)
{
#if defined(MBEDTLS_TEST_HOOKS)
    if (*mbedtls_test_hook_error_add != NULL) {
        (*mbedtls_test_hook_error_add)(high, low, file, line);
    }
#endif
    (void) file;
    (void) line;

    return high + low;
}

/**
 * \brief Translate an Mbed TLS error code into a string representation.
 *        The result is truncated if necessary and always includes a
 *        terminating null byte.
 *
 * \param errnum    error code
 * \param buffer    buffer to place representation in
 * \param buflen    length of the buffer
 */
void mbedtls_strerror(int errnum, char *buffer, size_t buflen);

/**
 * \brief Translate the high-level part of an Mbed TLS error code into a string
 *        representation.
 *
 * This function returns a const pointer to an un-modifiable string. The caller
 * must not try to modify the string. It is intended to be used mostly for
 * logging purposes.
 *
 * \param error_code    error code
 *
 * \return The string representation of the error code, or \c NULL if the error
 *         code is unknown.
 */
const char *mbedtls_high_level_strerr(int error_code);

/**
 * \brief Translate the low-level part of an Mbed TLS error code into a string
 *        representation.
 *
 * This function returns a const pointer to an un-modifiable string. The caller
 * must not try to modify the string. It is intended to be used mostly for
 * logging purposes.
 *
 * \param error_code    error code
 *
 * \return The string representation of the error code, or \c NULL if the error
 *         code is unknown.
 */
const char *mbedtls_low_level_strerr(int error_code);

#ifdef __cplusplus
}
#endif

#endif /* error.h */

Coverage Report

Created: 2026-10-17 06:10

Line	Count	Source
1		/**
2		* \file error.h
3		*
4		* \brief Error to string translation
5		*/
6		/*
7		* Copyright The Mbed TLS Contributors
8		* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
9		*/
10		#ifndef MBEDTLS_ERROR_H
11		#define MBEDTLS_ERROR_H
12
13		#include "mbedtls/build_info.h"
14
15		#include <stddef.h>
16
17		/**
18		* Error code layout.
19		*
20		* Currently we try to keep all error codes within the negative space of 16
21		* bits signed integers to support all platforms (-0x0001 - -0x7FFF). In
22		* addition we'd like to give two layers of information on the error if
23		* possible.
24		*
25		* For that purpose the error codes are segmented in the following manner:
26		*
27		* 16 bit error code bit-segmentation
28		*
29		* 1 bit - Unused (sign bit)
30		* 3 bits - High level module ID
31		* 5 bits - Module-dependent error code
32		* 7 bits - Low level module errors
33		*
34		* For historical reasons, low-level error codes are divided in even and odd,
35		* even codes were assigned first, and -1 is reserved for other errors.
36		*
37		* Low-level module errors (0x0002-0x007E, 0x0001-0x007F)
38		*
39		* Module Nr Codes assigned
40		* ERROR 2 0x006E 0x0001
41		* MPI 7 0x0002-0x0010
42		* GCM 3 0x0012-0x0016 0x0013-0x0013
43		* THREADING 3 0x001A-0x001E
44		* AES 5 0x0020-0x0022 0x0021-0x0025
45		* CAMELLIA 3 0x0024-0x0026 0x0027-0x0027
46		* BASE64 2 0x002A-0x002C
47		* OID 1 0x002E-0x002E 0x000B-0x000B
48		* PADLOCK 1 0x0030-0x0030
49		* DES 2 0x0032-0x0032 0x0033-0x0033
50		* CTR_DBRG 4 0x0034-0x003A
51		* ENTROPY 3 0x003C-0x0040 0x003D-0x003F
52		* NET 13 0x0042-0x0052 0x0043-0x0049
53		* ARIA 4 0x0058-0x005E
54		* ASN1 7 0x0060-0x006C
55		* CMAC 1 0x007A-0x007A
56		* PBKDF2 1 0x007C-0x007C
57		* HMAC_DRBG 4 0x0003-0x0009
58		* CCM 3 0x000D-0x0011
59		* MD5 1 0x002F-0x002F
60		* RIPEMD160 1 0x0031-0x0031
61		* SHA1 1 0x0035-0x0035 0x0073-0x0073
62		* SHA256 1 0x0037-0x0037 0x0074-0x0074
63		* SHA512 1 0x0039-0x0039 0x0075-0x0075
64		* SHA-3 1 0x0076-0x0076
65		* CHACHA20 3 0x0051-0x0055
66		* POLY1305 3 0x0057-0x005B
67		* CHACHAPOLY 2 0x0054-0x0056
68		* PLATFORM 2 0x0070-0x0072
69		* LMS 5 0x0011-0x0019
70		*
71		* High-level module nr (3 bits - 0x0...-0x7...)
72		* Name ID Nr of Errors
73		* PEM 1 9
74		* PKCS#12 1 4 (Started from top)
75		* X509 2 20
76		* PKCS5 2 4 (Started from top)
77		* DHM 3 11
78		* PK 3 15 (Started from top)
79		* RSA 4 11
80		* ECP 4 10 (Started from top)
81		* MD 5 5
82		* HKDF 5 1 (Started from top)
83		* PKCS7 5 12 (Started from 0x5300)
84		* SSL 5 3 (Started from 0x5F00)
85		* CIPHER 6 8 (Started from 0x6080)
86		* SSL 6 22 (Started from top, plus 0x6000)
87		* SSL 7 20 (Started from 0x7000, gaps at
88		* 0x7380, 0x7900-0x7980, 0x7A80-0x7E80)
89		*
90		* Module dependent error code (5 bits 0x.00.-0x.F8.)
91		*/
92
93		#ifdef __cplusplus
94		extern "C" {
95		#endif
96
97		/** Generic error */
98	0	#define MBEDTLS_ERR_ERROR_GENERIC_ERROR -0x0001
99		/** This is a bug in the library */
100	0	#define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E
101
102		/** Hardware accelerator failed */
103	0	#define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED -0x0070
104		/** The requested feature is not supported by the platform */
105	0	#define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072
106
107		/**
108		* \brief Combines a high-level and low-level error code together.
109		*
110		* Wrapper macro for mbedtls_error_add(). See that function for
111		* more details.
112		*/
113		#define MBEDTLS_ERROR_ADD(high, low) \
114	0	mbedtls_error_add(high, low, __FILE__, __LINE__)
115
116		#if defined(MBEDTLS_TEST_HOOKS)
117		/**
118		* \brief Testing hook called before adding/combining two error codes together.
119		* Only used when invasive testing is enabled via MBEDTLS_TEST_HOOKS.
120		*/
121		extern void (mbedtls_test_hook_error_add)(int, int, const char , int);
122		#endif
123
124		/**
125		* \brief Combines a high-level and low-level error code together.
126		*
127		* This function can be called directly however it is usually
128		* called via the #MBEDTLS_ERROR_ADD macro.
129		*
130		* While a value of zero is not a negative error code, it is still an
131		* error code (that denotes success) and can be combined with both a
132		* negative error code or another value of zero.
133		*
134		* \note When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to
135		* call \link mbedtls_test_hook_error_add \endlink.
136		*
137		* \param high high-level error code. See error.h for more details.
138		* \param low low-level error code. See error.h for more details.
139		* \param file file where this error code addition occurred.
140		* \param line line where this error code addition occurred.
141		*/
142		static inline int mbedtls_error_add(int high, int low,
143		const char *file, int line)
144	0	{
145		#if defined(MBEDTLS_TEST_HOOKS)
146		if (*mbedtls_test_hook_error_add != NULL) {
147		(*mbedtls_test_hook_error_add)(high, low, file, line);
148		}
149		#endif
150	0	(void) file;
151	0	(void) line;
152
153	0	return high + low;
154	0	} Unexecuted instantiation: x509.c:mbedtls_error_add Unexecuted instantiation: x509_crl.c:mbedtls_error_add Unexecuted instantiation: x509_crt.c:mbedtls_error_add Unexecuted instantiation: x509write_csr.c:mbedtls_error_add Unexecuted instantiation: x509_create.c:mbedtls_error_add Unexecuted instantiation: x509write.c:mbedtls_error_add Unexecuted instantiation: aes.c:mbedtls_error_add Unexecuted instantiation: asn1parse.c:mbedtls_error_add Unexecuted instantiation: asn1write.c:mbedtls_error_add Unexecuted instantiation: bignum.c:mbedtls_error_add Unexecuted instantiation: bignum_core.c:mbedtls_error_add Unexecuted instantiation: constant_time.c:mbedtls_error_add Unexecuted instantiation: ctr_drbg.c:mbedtls_error_add Unexecuted instantiation: entropy.c:mbedtls_error_add Unexecuted instantiation: entropy_poll.c:mbedtls_error_add Unexecuted instantiation: md.c:mbedtls_error_add Unexecuted instantiation: md5.c:mbedtls_error_add Unexecuted instantiation: oid.c:mbedtls_error_add Unexecuted instantiation: pem.c:mbedtls_error_add Unexecuted instantiation: pk.c:mbedtls_error_add Unexecuted instantiation: pk_ecc.c:mbedtls_error_add Unexecuted instantiation: pk_wrap.c:mbedtls_error_add Unexecuted instantiation: pkparse.c:mbedtls_error_add Unexecuted instantiation: pkwrite.c:mbedtls_error_add Unexecuted instantiation: psa_crypto.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_aead.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_hash.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_mac.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_pake.c:mbedtls_error_add Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_error_add Unexecuted instantiation: psa_util.c:mbedtls_error_add Unexecuted instantiation: ripemd160.c:mbedtls_error_add Unexecuted instantiation: rsa.c:mbedtls_error_add Unexecuted instantiation: sha1.c:mbedtls_error_add Unexecuted instantiation: sha256.c:mbedtls_error_add Unexecuted instantiation: sha512.c:mbedtls_error_add Unexecuted instantiation: sha3.c:mbedtls_error_add Unexecuted instantiation: base64.c:mbedtls_error_add Unexecuted instantiation: ccm.c:mbedtls_error_add Unexecuted instantiation: chachapoly.c:mbedtls_error_add Unexecuted instantiation: cipher.c:mbedtls_error_add Unexecuted instantiation: cipher_wrap.c:mbedtls_error_add Unexecuted instantiation: cmac.c:mbedtls_error_add Unexecuted instantiation: des.c:mbedtls_error_add Unexecuted instantiation: ecdh.c:mbedtls_error_add Unexecuted instantiation: ecdsa.c:mbedtls_error_add Unexecuted instantiation: ecjpake.c:mbedtls_error_add Unexecuted instantiation: ecp.c:mbedtls_error_add Unexecuted instantiation: ecp_curves.c:mbedtls_error_add Unexecuted instantiation: gcm.c:mbedtls_error_add Unexecuted instantiation: hmac_drbg.c:mbedtls_error_add Unexecuted instantiation: nist_kw.c:mbedtls_error_add Unexecuted instantiation: pkcs12.c:mbedtls_error_add Unexecuted instantiation: pkcs5.c:mbedtls_error_add Unexecuted instantiation: poly1305.c:mbedtls_error_add Unexecuted instantiation: chacha20.c:mbedtls_error_add
155
156		/**
157		* \brief Translate an Mbed TLS error code into a string representation.
158		* The result is truncated if necessary and always includes a
159		* terminating null byte.
160		*
161		* \param errnum error code
162		* \param buffer buffer to place representation in
163		* \param buflen length of the buffer
164		*/
165		void mbedtls_strerror(int errnum, char *buffer, size_t buflen);
166
167		/**
168		* \brief Translate the high-level part of an Mbed TLS error code into a string
169		* representation.
170		*
171		* This function returns a const pointer to an un-modifiable string. The caller
172		* must not try to modify the string. It is intended to be used mostly for
173		* logging purposes.
174		*
175		* \param error_code error code
176		*
177		* \return The string representation of the error code, or \c NULL if the error
178		* code is unknown.
179		*/
180		const char *mbedtls_high_level_strerr(int error_code);
181
182		/**
183		* \brief Translate the low-level part of an Mbed TLS error code into a string
184		* representation.
185		*
186		* This function returns a const pointer to an un-modifiable string. The caller
187		* must not try to modify the string. It is intended to be used mostly for
188		* logging purposes.
189		*
190		* \param error_code error code
191		*
192		* \return The string representation of the error code, or \c NULL if the error
193		* code is unknown.
194		*/
195		const char *mbedtls_low_level_strerr(int error_code);
196
197		#ifdef __cplusplus
198		}
199		#endif
200
201		#endif /* error.h */