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
9  *
10  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
11  *  not use this file except in compliance with the License.
12  *  You may obtain a copy of the License at
13  *
14  *  http://www.apache.org/licenses/LICENSE-2.0
15  *
16  *  Unless required by applicable law or agreed to in writing, software
17  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  *  See the License for the specific language governing permissions and
20  *  limitations under the License.
21  */
22 #ifndef MBEDTLS_ERROR_H
23 #define MBEDTLS_ERROR_H
24 
25 #include "mbedtls/build_info.h"
26 
27 #include <stddef.h>
28 
29 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
30     !defined(inline) && !defined(__cplusplus)
31 #define inline __inline
32 #endif
33 
34 /**
35  * Error code layout.
36  *
37  * Currently we try to keep all error codes within the negative space of 16
38  * bits signed integers to support all platforms (-0x0001 - -0x7FFF). In
39  * addition we'd like to give two layers of information on the error if
40  * possible.
41  *
42  * For that purpose the error codes are segmented in the following manner:
43  *
44  * 16 bit error code bit-segmentation
45  *
46  * 1 bit  - Unused (sign bit)
47  * 3 bits - High level module ID
48  * 5 bits - Module-dependent error code
49  * 7 bits - Low level module errors
50  *
51  * For historical reasons, low-level error codes are divided in even and odd,
52  * even codes were assigned first, and -1 is reserved for other errors.
53  *
54  * Low-level module errors (0x0002-0x007E, 0x0001-0x007F)
55  *
56  * Module   Nr  Codes assigned
57  * ERROR     2  0x006E          0x0001
58  * MPI       7  0x0002-0x0010
59  * GCM       3  0x0012-0x0016   0x0013-0x0013
60  * THREADING 3  0x001A-0x001E
61  * AES       5  0x0020-0x0022   0x0021-0x0025
62  * CAMELLIA  3  0x0024-0x0026   0x0027-0x0027
63  * BASE64    2  0x002A-0x002C
64  * OID       1  0x002E-0x002E   0x000B-0x000B
65  * PADLOCK   1  0x0030-0x0030
66  * DES       2  0x0032-0x0032   0x0033-0x0033
67  * CTR_DBRG  4  0x0034-0x003A
68  * ENTROPY   3  0x003C-0x0040   0x003D-0x003F
69  * NET      13  0x0042-0x0052   0x0043-0x0049
70  * ARIA      4  0x0058-0x005E
71  * ASN1      7  0x0060-0x006C
72  * CMAC      1  0x007A-0x007A
73  * PBKDF2    1  0x007C-0x007C
74  * HMAC_DRBG 4                  0x0003-0x0009
75  * CCM       3                  0x000D-0x0011
76  * MD5       1                  0x002F-0x002F
77  * RIPEMD160 1                  0x0031-0x0031
78  * SHA1      1                  0x0035-0x0035 0x0073-0x0073
79  * SHA256    1                  0x0037-0x0037 0x0074-0x0074
80  * SHA512    1                  0x0039-0x0039 0x0075-0x0075
81  * CHACHA20  3                  0x0051-0x0055
82  * POLY1305  3                  0x0057-0x005B
83  * CHACHAPOLY 2 0x0054-0x0056
84  * PLATFORM  2  0x0070-0x0072
85  *
86  * High-level module nr (3 bits - 0x0...-0x7...)
87  * Name      ID  Nr of Errors
88  * PEM       1   9
89  * PKCS#12   1   4 (Started from top)
90  * X509      2   20
91  * PKCS5     2   4 (Started from top)
92  * DHM       3   11
93  * PK        3   15 (Started from top)
94  * RSA       4   11
95  * ECP       4   10 (Started from top)
96  * MD        5   5
97  * HKDF      5   1 (Started from top)
98  * SSL       5   2 (Started from 0x5F00)
99  * CIPHER    6   8 (Started from 0x6080)
100  * SSL       6   22 (Started from top, plus 0x6000)
101  * SSL       7   20 (Started from 0x7000, gaps at
102  *                   0x7380, 0x7900-0x7980, 0x7A80-0x7E80)
103  *
104  * Module dependent error code (5 bits 0x.00.-0x.F8.)
105  */
106 
107 #ifdef __cplusplus
108 extern "C" {
109 #endif
110 
111 /** Generic error */
112 #define MBEDTLS_ERR_ERROR_GENERIC_ERROR       -0x0001
113 /** This is a bug in the library */
114 #define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E
115 
116 /** Hardware accelerator failed */
117 #define MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED     -0x0070
118 /** The requested feature is not supported by the platform */
119 #define MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED -0x0072
120 
121 /**
122  * \brief Combines a high-level and low-level error code together.
123  *
124  *        Wrapper macro for mbedtls_error_add(). See that function for
125  *        more details.
126  */
127 #define MBEDTLS_ERROR_ADD( high, low ) \
128         mbedtls_error_add( high, low, __FILE__, __LINE__ )
129 
130 #if defined(MBEDTLS_TEST_HOOKS)
131 /**
132  * \brief Testing hook called before adding/combining two error codes together.
133  *        Only used when invasive testing is enabled via MBEDTLS_TEST_HOOKS.
134  */
135 extern void (*mbedtls_test_hook_error_add)( int, int, const char *, int );
136 #endif
137 
138 /**
139  * \brief Combines a high-level and low-level error code together.
140  *
141  *        This function can be called directly however it is usually
142  *        called via the #MBEDTLS_ERROR_ADD macro.
143  *
144  *        While a value of zero is not a negative error code, it is still an
145  *        error code (that denotes success) and can be combined with both a
146  *        negative error code or another value of zero.
147  *
148  * \note  When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to
149  *        call \link mbedtls_test_hook_error_add \endlink.
150  *
151  * \param high      high-level error code. See error.h for more details.
152  * \param low       low-level error code. See error.h for more details.
153  * \param file      file where this error code addition occurred.
154  * \param line      line where this error code addition occurred.
155  */
mbedtls_error_add(int high,int low,const char * file,int line)156 static inline int mbedtls_error_add( int high, int low,
157                                      const char *file, int line )
158 {
159 #if defined(MBEDTLS_TEST_HOOKS)
160     if( *mbedtls_test_hook_error_add != NULL )
161         ( *mbedtls_test_hook_error_add )( high, low, file, line );
162 #endif
163     (void)file;
164     (void)line;
165 
166     return( high + low );
167 }
168 
169 /**
170  * \brief Translate a mbed TLS error code into a string representation,
171  *        Result is truncated if necessary and always includes a terminating
172  *        null byte.
173  *
174  * \param errnum    error code
175  * \param buffer    buffer to place representation in
176  * \param buflen    length of the buffer
177  */
178 void mbedtls_strerror( int errnum, char *buffer, size_t buflen );
179 
180 /**
181  * \brief Translate the high-level part of an Mbed TLS error code into a string
182  *        representation.
183  *
184  * This function returns a const pointer to an un-modifiable string. The caller
185  * must not try to modify the string. It is intended to be used mostly for
186  * logging purposes.
187  *
188  * \param error_code    error code
189  *
190  * \return The string representation of the error code, or \c NULL if the error
191  *         code is unknown.
192  */
193 const char * mbedtls_high_level_strerr( int error_code );
194 
195 /**
196  * \brief Translate the low-level part of an Mbed TLS error code into a string
197  *        representation.
198  *
199  * This function returns a const pointer to an un-modifiable string. The caller
200  * must not try to modify the string. It is intended to be used mostly for
201  * logging purposes.
202  *
203  * \param error_code    error code
204  *
205  * \return The string representation of the error code, or \c NULL if the error
206  *         code is unknown.
207  */
208 const char * mbedtls_low_level_strerr( int error_code );
209 
210 #ifdef __cplusplus
211 }
212 #endif
213 
214 #endif /* error.h */
215