helpers.h (14721B)
1 /** 2 * \file helpers.h 3 * 4 * \brief This file contains the prototypes of helper functions for the 5 * purpose of testing. 6 */ 7 8 /* 9 * Copyright The Mbed TLS Contributors 10 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 11 */ 12 13 #ifndef TEST_HELPERS_H 14 #define TEST_HELPERS_H 15 16 /* Most fields of publicly available structs are private and are wrapped with 17 * MBEDTLS_PRIVATE macro. This define allows tests to access the private fields 18 * directly (without using the MBEDTLS_PRIVATE wrapper). */ 19 #define MBEDTLS_ALLOW_PRIVATE_ACCESS 20 21 #include "mbedtls/build_info.h" 22 23 #if defined(__SANITIZE_ADDRESS__) /* gcc -fsanitize=address */ 24 # define MBEDTLS_TEST_HAVE_ASAN 25 #endif 26 #if defined(__SANITIZE_THREAD__) /* gcc -fsanitize-thread */ 27 # define MBEDTLS_TEST_HAVE_TSAN 28 #endif 29 30 #if defined(__has_feature) 31 # if __has_feature(address_sanitizer) /* clang -fsanitize=address */ 32 # define MBEDTLS_TEST_HAVE_ASAN 33 # endif 34 # if __has_feature(memory_sanitizer) /* clang -fsanitize=memory */ 35 # define MBEDTLS_TEST_HAVE_MSAN 36 # endif 37 # if __has_feature(thread_sanitizer) /* clang -fsanitize=thread */ 38 # define MBEDTLS_TEST_HAVE_TSAN 39 # endif 40 #endif 41 42 #include "test/threading_helpers.h" 43 44 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 45 #include "mbedtls/threading.h" 46 #endif 47 48 #include "mbedtls/platform.h" 49 50 #include <stddef.h> 51 #include <stdint.h> 52 53 #if defined(MBEDTLS_BIGNUM_C) 54 #include "mbedtls/bignum.h" 55 #endif 56 57 /** The type of test case arguments that contain binary data. */ 58 typedef struct data_tag { 59 uint8_t *x; 60 uint32_t len; 61 } data_t; 62 63 typedef enum { 64 MBEDTLS_TEST_RESULT_SUCCESS = 0, 65 MBEDTLS_TEST_RESULT_FAILED, 66 MBEDTLS_TEST_RESULT_SKIPPED 67 } mbedtls_test_result_t; 68 69 #define MBEDTLS_TEST_LINE_LENGTH 76 70 71 typedef struct { 72 mbedtls_test_result_t result; 73 const char *test; 74 const char *filename; 75 int line_no; 76 unsigned long step; 77 char line1[MBEDTLS_TEST_LINE_LENGTH]; 78 char line2[MBEDTLS_TEST_LINE_LENGTH]; 79 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 80 const char *mutex_usage_error; 81 #endif 82 #if defined(MBEDTLS_BIGNUM_C) 83 unsigned case_uses_negative_0; 84 #endif 85 } 86 mbedtls_test_info_t; 87 88 /** 89 * \brief Get the current test result status 90 * 91 * \return The current test result status 92 */ 93 mbedtls_test_result_t mbedtls_test_get_result(void); 94 95 /** 96 * \brief Get the current test name/description 97 * 98 * \return The current test name/description 99 */ 100 const char *mbedtls_test_get_test(void); 101 102 /** 103 * \brief Get the current test filename 104 * 105 * \return The current test filename 106 */ 107 const char *mbedtls_get_test_filename(void); 108 109 /** 110 * \brief Get the current test file line number (for failure / skip) 111 * 112 * \return The current test file line number (for failure / skip) 113 */ 114 int mbedtls_test_get_line_no(void); 115 116 /** 117 * \brief Increment the current test step. 118 * 119 * \note It is not recommended for multiple threads to call this 120 * function concurrently - whilst it is entirely thread safe, 121 * the order of calls to this function can obviously not be 122 * ensured, so unexpected results may occur. 123 */ 124 void mbedtls_test_increment_step(void); 125 126 /** 127 * \brief Get the current test step 128 * 129 * \return The current test step 130 */ 131 unsigned long mbedtls_test_get_step(void); 132 133 /** 134 * \brief Get the current test line buffer 1 135 * 136 * \param line Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH, 137 * which will have line buffer 1 copied to it. 138 */ 139 void mbedtls_test_get_line1(char *line); 140 141 /** 142 * \brief Get the current test line buffer 2 143 * 144 * \param line Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH, 145 * which will have line buffer 1 copied to it. 146 */ 147 void mbedtls_test_get_line2(char *line); 148 149 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 150 /** 151 * \brief Get the current mutex usage error message 152 * 153 * \return The current mutex error message (may be NULL if no error) 154 */ 155 const char *mbedtls_test_get_mutex_usage_error(void); 156 157 /** 158 * \brief Set the current mutex usage error message 159 * 160 * \note This will only set the mutex error message if one has not 161 * already been set, or if we are clearing the message (msg is 162 * NULL) 163 * 164 * \param msg Error message to set (can be NULL to clear) 165 */ 166 void mbedtls_test_set_mutex_usage_error(const char *msg); 167 #endif 168 169 /** 170 * \brief Check whether the given buffer is all-bits-zero. 171 * 172 * \param[in] buf Pointer to the buffer to check. 173 * \param size Buffer size in bytes. 174 * 175 * \retval 0 The given buffer has a nonzero byte. 176 * \retval 1 The given buffer is all-bits-zero (this includes the case 177 * of an empty buffer). 178 */ 179 int mbedtls_test_buffer_is_all_zero(const uint8_t *buf, size_t size); 180 181 /** Check whether the object at the given address is all-bits-zero. 182 * 183 * \param[in] ptr A pointer to the object to check. 184 * This macro parameter may be evaluated more than once. 185 * 186 * \retval 0 The given object has a nonzero byte. 187 * \retval 1 The given object is all-bits-zero (this includes the case 188 * of an empty buffer). 189 */ 190 #define MBEDTLS_TEST_OBJECT_IS_ALL_ZERO(ptr) \ 191 (mbedtls_test_buffer_is_all_zero((const uint8_t *) (ptr), sizeof(*(ptr)))) 192 193 #if defined(MBEDTLS_BIGNUM_C) 194 195 /** 196 * \brief Get whether the current test is a bignum test that uses 197 * negative zero. 198 * 199 * \return non zero if the current test uses bignum negative zero. 200 */ 201 unsigned mbedtls_test_get_case_uses_negative_0(void); 202 203 /** 204 * \brief Indicate that the current test uses bignum negative zero. 205 * 206 * \note This function is called if the current test case had an 207 * input parsed with mbedtls_test_read_mpi() that is a negative 208 * 0 (`"-"`, `"-0"`, `"-00"`, etc., constructing a result with 209 * the sign bit set to -1 and the value being all-limbs-0, 210 * which is not a valid representation in #mbedtls_mpi but is 211 * tested for robustness). * 212 */ 213 void mbedtls_test_increment_case_uses_negative_0(void); 214 #endif 215 216 int mbedtls_test_platform_setup(void); 217 void mbedtls_test_platform_teardown(void); 218 219 /** 220 * \brief Record the current test case as a failure. 221 * 222 * This function can be called directly however it is usually 223 * called via macros such as TEST_ASSERT, TEST_EQUAL, 224 * PSA_ASSERT, etc... 225 * 226 * \note If the test case was already marked as failed, calling 227 * `mbedtls_test_fail( )` again will not overwrite any 228 * previous information about the failure. 229 * 230 * \param test Description of the failure or assertion that failed. This 231 * MUST be a string literal. 232 * \param line_no Line number where the failure originated. 233 * \param filename Filename where the failure originated. 234 */ 235 void mbedtls_test_fail(const char *test, int line_no, const char *filename); 236 237 /** 238 * \brief Record the current test case as skipped. 239 * 240 * This function can be called directly however it is usually 241 * called via the TEST_ASSUME macro. 242 * 243 * \param test Description of the assumption that caused the test case to 244 * be skipped. This MUST be a string literal. 245 * \param line_no Line number where the test case was skipped. 246 * \param filename Filename where the test case was skipped. 247 */ 248 void mbedtls_test_skip(const char *test, int line_no, const char *filename); 249 250 /** 251 * \brief Set the test step number for failure reports. 252 * 253 * Call this function to display "step NNN" in addition to the 254 * line number and file name if a test fails. Typically the 255 * "step number" is the index of a for loop but it can be 256 * whatever you want. 257 * 258 * \note It is not recommended for multiple threads to call this 259 * function concurrently - whilst it is entirely thread safe, 260 * the order of calls to this function can obviously not be 261 * ensured, so unexpected results may occur. 262 * 263 * \param step The step number to report. 264 */ 265 void mbedtls_test_set_step(unsigned long step); 266 267 /** 268 * \brief Reset mbedtls_test_info to a ready/starting state. 269 */ 270 void mbedtls_test_info_reset(void); 271 272 #ifdef MBEDTLS_TEST_MUTEX_USAGE 273 /** 274 * \brief Get the test info data mutex. 275 * 276 * \note This is designed only to be used by threading_helpers to 277 * avoid a deadlock, not for general access to this mutex. 278 * 279 * \return The test info data mutex. 280 */ 281 mbedtls_threading_mutex_t *mbedtls_test_get_info_mutex(void); 282 283 #endif /* MBEDTLS_TEST_MUTEX_USAGE */ 284 285 /** 286 * \brief Record the current test case as a failure if two integers 287 * have a different value. 288 * 289 * This function is usually called via the macro 290 * #TEST_EQUAL. 291 * 292 * \param test Description of the failure or assertion that failed. This 293 * MUST be a string literal. This normally has the form 294 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1 295 * and EXPR2 has the value \p value2. 296 * \param line_no Line number where the failure originated. 297 * \param filename Filename where the failure originated. 298 * \param value1 The first value to compare. 299 * \param value2 The second value to compare. 300 * 301 * \return \c 1 if the values are equal, otherwise \c 0. 302 */ 303 int mbedtls_test_equal(const char *test, int line_no, const char *filename, 304 unsigned long long value1, unsigned long long value2); 305 306 /** 307 * \brief Record the current test case as a failure based 308 * on comparing two unsigned integers. 309 * 310 * This function is usually called via the macro 311 * #TEST_LE_U. 312 * 313 * \param test Description of the failure or assertion that failed. This 314 * MUST be a string literal. This normally has the form 315 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 316 * and EXPR2 has the value \p value2. 317 * \param line_no Line number where the failure originated. 318 * \param filename Filename where the failure originated. 319 * \param value1 The first value to compare. 320 * \param value2 The second value to compare. 321 * 322 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 323 */ 324 int mbedtls_test_le_u(const char *test, int line_no, const char *filename, 325 unsigned long long value1, unsigned long long value2); 326 327 /** 328 * \brief Record the current test case as a failure based 329 * on comparing two signed integers. 330 * 331 * This function is usually called via the macro 332 * #TEST_LE_S. 333 * 334 * \param test Description of the failure or assertion that failed. This 335 * MUST be a string literal. This normally has the form 336 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 337 * and EXPR2 has the value \p value2. 338 * \param line_no Line number where the failure originated. 339 * \param filename Filename where the failure originated. 340 * \param value1 The first value to compare. 341 * \param value2 The second value to compare. 342 * 343 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 344 */ 345 int mbedtls_test_le_s(const char *test, int line_no, const char *filename, 346 long long value1, long long value2); 347 348 /** 349 * \brief This function decodes the hexadecimal representation of 350 * data. 351 * 352 * \note The output buffer can be the same as the input buffer. For 353 * any other overlapping of the input and output buffers, the 354 * behavior is undefined. 355 * 356 * \param obuf Output buffer. 357 * \param obufmax Size in number of bytes of \p obuf. 358 * \param ibuf Input buffer. 359 * \param len The number of unsigned char written in \p obuf. This must 360 * not be \c NULL. 361 * 362 * \return \c 0 on success. 363 * \return \c -1 if the output buffer is too small or the input string 364 * is not a valid hexadecimal representation. 365 */ 366 int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax, 367 const char *ibuf, size_t *len); 368 369 void mbedtls_test_hexify(unsigned char *obuf, 370 const unsigned char *ibuf, 371 int len); 372 373 /** 374 * \brief Convert hexadecimal digit to an integer. 375 * 376 * \param c The digit to convert (`'0'` to `'9'`, `'A'` to `'F'` or 377 * `'a'` to `'f'`). 378 * \param[out] uc On success, the value of the digit (0 to 15). 379 * 380 * \return 0 on success, -1 if \p c is not a hexadecimal digit. 381 */ 382 int mbedtls_test_ascii2uc(const char c, unsigned char *uc); 383 384 /** 385 * Allocate and zeroize a buffer. 386 * 387 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 388 * 389 * For convenience, dies if allocation fails. 390 */ 391 unsigned char *mbedtls_test_zero_alloc(size_t len); 392 393 /** 394 * Allocate and fill a buffer from hex data. 395 * 396 * The buffer is sized exactly as needed. This allows to detect buffer 397 * overruns (including overreads) when running the test suite under valgrind. 398 * 399 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 400 * 401 * For convenience, dies if allocation fails. 402 */ 403 unsigned char *mbedtls_test_unhexify_alloc(const char *ibuf, size_t *olen); 404 405 int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b, 406 uint32_t a_len, uint32_t b_len); 407 408 #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 409 #include "test/fake_external_rng_for_test.h" 410 #endif 411 412 #if defined(MBEDTLS_TEST_HOOKS) 413 /** 414 * \brief Check that only a pure high-level error code is being combined with 415 * a pure low-level error code as otherwise the resultant error code 416 * would be corrupted. 417 * 418 * \note Both high-level and low-level error codes cannot be greater than 419 * zero however can be zero. If one error code is zero then the 420 * other error code is returned even if both codes are zero. 421 * 422 * \note If the check fails, fail the test currently being run. 423 */ 424 void mbedtls_test_err_add_check(int high, int low, 425 const char *file, int line); 426 #endif 427 428 #endif /* TEST_HELPERS_H */