error.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215
  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. #if !defined(MBEDTLS_CONFIG_FILE)
  25. #include "mbedtls/config.h"
  26. #else
  27. #include MBEDTLS_CONFIG_FILE
  28. #endif
  29. #include <stddef.h>
  30. #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
  31. !defined(inline) && !defined(__cplusplus)
  32. #define inline __inline
  33. #endif
  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-0x0014 0x0013-0x0013
  60. * BLOWFISH 3 0x0016-0x0018 0x0017-0x0017
  61. * THREADING 3 0x001A-0x001E
  62. * AES 5 0x0020-0x0022 0x0021-0x0025
  63. * CAMELLIA 3 0x0024-0x0026 0x0027-0x0027
  64. * XTEA 2 0x0028-0x0028 0x0029-0x0029
  65. * BASE64 2 0x002A-0x002C
  66. * OID 1 0x002E-0x002E 0x000B-0x000B
  67. * PADLOCK 1 0x0030-0x0030
  68. * DES 2 0x0032-0x0032 0x0033-0x0033
  69. * CTR_DBRG 4 0x0034-0x003A
  70. * ENTROPY 3 0x003C-0x0040 0x003D-0x003F
  71. * NET 13 0x0042-0x0052 0x0043-0x0049
  72. * ARIA 4 0x0058-0x005E
  73. * ASN1 7 0x0060-0x006C
  74. * CMAC 1 0x007A-0x007A
  75. * PBKDF2 1 0x007C-0x007C
  76. * HMAC_DRBG 4 0x0003-0x0009
  77. * CCM 3 0x000D-0x0011
  78. * ARC4 1 0x0019-0x0019
  79. * MD2 1 0x002B-0x002B
  80. * MD4 1 0x002D-0x002D
  81. * MD5 1 0x002F-0x002F
  82. * RIPEMD160 1 0x0031-0x0031
  83. * SHA1 1 0x0035-0x0035 0x0073-0x0073
  84. * SHA256 1 0x0037-0x0037 0x0074-0x0074
  85. * SHA512 1 0x0039-0x0039 0x0075-0x0075
  86. * CHACHA20 3 0x0051-0x0055
  87. * POLY1305 3 0x0057-0x005B
  88. * CHACHAPOLY 2 0x0054-0x0056
  89. * PLATFORM 2 0x0070-0x0072
  90. *
  91. * High-level module nr (3 bits - 0x0...-0x7...)
  92. * Name ID Nr of Errors
  93. * PEM 1 9
  94. * PKCS#12 1 4 (Started from top)
  95. * X509 2 20
  96. * PKCS5 2 4 (Started from top)
  97. * DHM 3 11
  98. * PK 3 15 (Started from top)
  99. * RSA 4 11
  100. * ECP 4 10 (Started from top)
  101. * MD 5 5
  102. * HKDF 5 1 (Started from top)
  103. * SSL 5 2 (Started from 0x5F00)
  104. * CIPHER 6 8 (Started from 0x6080)
  105. * SSL 6 24 (Started from top, plus 0x6000)
  106. * SSL 7 32
  107. *
  108. * Module dependent error code (5 bits 0x.00.-0x.F8.)
  109. */
  110. #ifdef __cplusplus
  111. extern "C" {
  112. #endif
  113. #define MBEDTLS_ERR_ERROR_GENERIC_ERROR -0x0001 /**< Generic error */
  114. #define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E /**< This is a bug in the library */
  115. /**
  116. * \brief Combines a high-level and low-level error code together.
  117. *
  118. * Wrapper macro for mbedtls_error_add(). See that function for
  119. * more details.
  120. */
  121. #define MBEDTLS_ERROR_ADD( high, low ) \
  122. mbedtls_error_add( high, low, __FILE__, __LINE__ )
  123. #if defined(MBEDTLS_TEST_HOOKS)
  124. /**
  125. * \brief Testing hook called before adding/combining two error codes together.
  126. * Only used when invasive testing is enabled via MBEDTLS_TEST_HOOKS.
  127. */
  128. extern void (*mbedtls_test_hook_error_add)( int, int, const char *, int );
  129. #endif
  130. /**
  131. * \brief Combines a high-level and low-level error code together.
  132. *
  133. * This function can be called directly however it is usually
  134. * called via the #MBEDTLS_ERROR_ADD macro.
  135. *
  136. * While a value of zero is not a negative error code, it is still an
  137. * error code (that denotes success) and can be combined with both a
  138. * negative error code or another value of zero.
  139. *
  140. * \note When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to
  141. * call \link mbedtls_test_hook_error_add \endlink.
  142. *
  143. * \param high high-level error code. See error.h for more details.
  144. * \param low low-level error code. See error.h for more details.
  145. * \param file file where this error code addition occurred.
  146. * \param line line where this error code addition occurred.
  147. */
  148. static inline int mbedtls_error_add( int high, int low,
  149. const char *file, int line )
  150. {
  151. #if defined(MBEDTLS_TEST_HOOKS)
  152. if( *mbedtls_test_hook_error_add != NULL )
  153. ( *mbedtls_test_hook_error_add )( high, low, file, line );
  154. #endif
  155. (void)file;
  156. (void)line;
  157. return( high + low );
  158. }
  159. /**
  160. * \brief Translate a mbed TLS error code into a string representation,
  161. * Result is truncated if necessary and always includes a terminating
  162. * null byte.
  163. *
  164. * \param errnum error code
  165. * \param buffer buffer to place representation in
  166. * \param buflen length of the buffer
  167. */
  168. void mbedtls_strerror( int errnum, char *buffer, size_t buflen );
  169. /**
  170. * \brief Translate the high-level part of an Mbed TLS error code into a string
  171. * representation.
  172. *
  173. * This function returns a const pointer to an un-modifiable string. The caller
  174. * must not try to modify the string. It is intended to be used mostly for
  175. * logging purposes.
  176. *
  177. * \param error_code error code
  178. *
  179. * \return The string representation of the error code, or \c NULL if the error
  180. * code is unknown.
  181. */
  182. const char * mbedtls_high_level_strerr( int error_code );
  183. /**
  184. * \brief Translate the low-level part of an Mbed TLS error code into a string
  185. * representation.
  186. *
  187. * This function returns a const pointer to an un-modifiable string. The caller
  188. * must not try to modify the string. It is intended to be used mostly for
  189. * logging purposes.
  190. *
  191. * \param error_code error code
  192. *
  193. * \return The string representation of the error code, or \c NULL if the error
  194. * code is unknown.
  195. */
  196. const char * mbedtls_low_level_strerr( int error_code );
  197. #ifdef __cplusplus
  198. }
  199. #endif
  200. #endif /* error.h */