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(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \ 24 defined(MBEDTLS_TEST_HOOKS) 25 #define MBEDTLS_TEST_MUTEX_USAGE 26 #endif 27 28 #include "mbedtls/platform.h" 29 30 #include <stddef.h> 31 #include <stdint.h> 32 33 #if defined(MBEDTLS_BIGNUM_C) 34 #include "mbedtls/bignum.h" 35 #endif 36 37 /** The type of test case arguments that contain binary data. */ 38 typedef struct data_tag { 39 uint8_t *x; 40 uint32_t len; 41 } data_t; 42 43 typedef enum { 44 MBEDTLS_TEST_RESULT_SUCCESS = 0, 45 MBEDTLS_TEST_RESULT_FAILED, 46 MBEDTLS_TEST_RESULT_SKIPPED 47 } mbedtls_test_result_t; 48 49 typedef struct { 50 mbedtls_test_result_t result; 51 const char *test; 52 const char *filename; 53 int line_no; 54 unsigned long step; 55 char line1[76]; 56 char line2[76]; 57 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 58 const char *mutex_usage_error; 59 #endif 60 } 61 mbedtls_test_info_t; 62 extern mbedtls_test_info_t mbedtls_test_info; 63 64 int mbedtls_test_platform_setup(void); 65 void mbedtls_test_platform_teardown(void); 66 67 /** 68 * \brief Record the current test case as a failure. 69 * 70 * This function can be called directly however it is usually 71 * called via macros such as TEST_ASSERT, TEST_EQUAL, 72 * PSA_ASSERT, etc... 73 * 74 * \note If the test case was already marked as failed, calling 75 * `mbedtls_test_fail( )` again will not overwrite any 76 * previous information about the failure. 77 * 78 * \param test Description of the failure or assertion that failed. This 79 * MUST be a string literal. 80 * \param line_no Line number where the failure originated. 81 * \param filename Filename where the failure originated. 82 */ 83 void mbedtls_test_fail(const char *test, int line_no, const char *filename); 84 85 /** 86 * \brief Record the current test case as skipped. 87 * 88 * This function can be called directly however it is usually 89 * called via the TEST_ASSUME macro. 90 * 91 * \param test Description of the assumption that caused the test case to 92 * be skipped. This MUST be a string literal. 93 * \param line_no Line number where the test case was skipped. 94 * \param filename Filename where the test case was skipped. 95 */ 96 void mbedtls_test_skip(const char *test, int line_no, const char *filename); 97 98 /** 99 * \brief Set the test step number for failure reports. 100 * 101 * Call this function to display "step NNN" in addition to the 102 * line number and file name if a test fails. Typically the "step 103 * number" is the index of a for loop but it can be whatever you 104 * want. 105 * 106 * \param step The step number to report. 107 */ 108 void mbedtls_test_set_step(unsigned long step); 109 110 /** 111 * \brief Reset mbedtls_test_info to a ready/starting state. 112 */ 113 void mbedtls_test_info_reset(void); 114 115 /** 116 * \brief Record the current test case as a failure if two integers 117 * have a different value. 118 * 119 * This function is usually called via the macro 120 * #TEST_EQUAL. 121 * 122 * \param test Description of the failure or assertion that failed. This 123 * MUST be a string literal. This normally has the form 124 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1 125 * and EXPR2 has the value \p value2. 126 * \param line_no Line number where the failure originated. 127 * \param filename Filename where the failure originated. 128 * \param value1 The first value to compare. 129 * \param value2 The second value to compare. 130 * 131 * \return \c 1 if the values are equal, otherwise \c 0. 132 */ 133 int mbedtls_test_equal(const char *test, int line_no, const char *filename, 134 unsigned long long value1, unsigned long long value2); 135 136 /** 137 * \brief Record the current test case as a failure based 138 * on comparing two unsigned integers. 139 * 140 * This function is usually called via the macro 141 * #TEST_LE_U. 142 * 143 * \param test Description of the failure or assertion that failed. This 144 * MUST be a string literal. This normally has the form 145 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 146 * and EXPR2 has the value \p value2. 147 * \param line_no Line number where the failure originated. 148 * \param filename Filename where the failure originated. 149 * \param value1 The first value to compare. 150 * \param value2 The second value to compare. 151 * 152 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 153 */ 154 int mbedtls_test_le_u(const char *test, int line_no, const char *filename, 155 unsigned long long value1, unsigned long long value2); 156 157 /** 158 * \brief Record the current test case as a failure based 159 * on comparing two signed integers. 160 * 161 * This function is usually called via the macro 162 * #TEST_LE_S. 163 * 164 * \param test Description of the failure or assertion that failed. This 165 * MUST be a string literal. This normally has the form 166 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 167 * and EXPR2 has the value \p value2. 168 * \param line_no Line number where the failure originated. 169 * \param filename Filename where the failure originated. 170 * \param value1 The first value to compare. 171 * \param value2 The second value to compare. 172 * 173 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 174 */ 175 int mbedtls_test_le_s(const char *test, int line_no, const char *filename, 176 long long value1, long long value2); 177 178 /** 179 * \brief This function decodes the hexadecimal representation of 180 * data. 181 * 182 * \note The output buffer can be the same as the input buffer. For 183 * any other overlapping of the input and output buffers, the 184 * behavior is undefined. 185 * 186 * \param obuf Output buffer. 187 * \param obufmax Size in number of bytes of \p obuf. 188 * \param ibuf Input buffer. 189 * \param len The number of unsigned char written in \p obuf. This must 190 * not be \c NULL. 191 * 192 * \return \c 0 on success. 193 * \return \c -1 if the output buffer is too small or the input string 194 * is not a valid hexadecimal representation. 195 */ 196 int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax, 197 const char *ibuf, size_t *len); 198 199 void mbedtls_test_hexify(unsigned char *obuf, 200 const unsigned char *ibuf, 201 int len); 202 203 /** 204 * \brief Convert hexadecimal digit to an integer. 205 * 206 * \param c The digit to convert (`'0'` to `'9'`, `'A'` to `'F'` or 207 * `'a'` to `'f'`). 208 * \param[out] uc On success, the value of the digit (0 to 15). 209 * 210 * \return 0 on success, -1 if \p c is not a hexadecimal digit. 211 */ 212 int mbedtls_test_ascii2uc(const char c, unsigned char *uc); 213 214 /** 215 * Allocate and zeroize a buffer. 216 * 217 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 218 * 219 * For convenience, dies if allocation fails. 220 */ 221 unsigned char *mbedtls_test_zero_alloc(size_t len); 222 223 /** 224 * Allocate and fill a buffer from hex data. 225 * 226 * The buffer is sized exactly as needed. This allows to detect buffer 227 * overruns (including overreads) when running the test suite under valgrind. 228 * 229 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 230 * 231 * For convenience, dies if allocation fails. 232 */ 233 unsigned char *mbedtls_test_unhexify_alloc(const char *ibuf, size_t *olen); 234 235 int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b, 236 uint32_t a_len, uint32_t b_len); 237 238 #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 239 #include "test/fake_external_rng_for_test.h" 240 #endif 241 242 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 243 /** Permanently activate the mutex usage verification framework. See 244 * threading_helpers.c for information. */ 245 void mbedtls_test_mutex_usage_init(void); 246 247 /** Call this function after executing a test case to check for mutex usage 248 * errors. */ 249 void mbedtls_test_mutex_usage_check(void); 250 #endif /* MBEDTLS_TEST_MUTEX_USAGE */ 251 252 #if defined(MBEDTLS_TEST_HOOKS) 253 /** 254 * \brief Check that only a pure high-level error code is being combined with 255 * a pure low-level error code as otherwise the resultant error code 256 * would be corrupted. 257 * 258 * \note Both high-level and low-level error codes cannot be greater than 259 * zero however can be zero. If one error code is zero then the 260 * other error code is returned even if both codes are zero. 261 * 262 * \note If the check fails, fail the test currently being run. 263 */ 264 void mbedtls_test_err_add_check(int high, int low, 265 const char *file, int line); 266 #endif 267 268 #endif /* TEST_HELPERS_H */ 269
