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 #if !defined(MBEDTLS_CONFIG_FILE) 17 #include "mbedtls/config.h" 18 #else 19 #include MBEDTLS_CONFIG_FILE 20 #endif 21 22 #if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \ 23 defined(MBEDTLS_TEST_HOOKS) 24 #define MBEDTLS_TEST_MUTEX_USAGE 25 #endif 26 27 #include "mbedtls/platform.h" 28 29 #include <stddef.h> 30 #include <stdint.h> 31 32 #if defined(MBEDTLS_BIGNUM_C) 33 #include "mbedtls/bignum.h" 34 #endif 35 36 /** The type of test case arguments that contain binary data. */ 37 typedef struct data_tag { 38 uint8_t *x; 39 uint32_t len; 40 } data_t; 41 42 typedef enum { 43 MBEDTLS_TEST_RESULT_SUCCESS = 0, 44 MBEDTLS_TEST_RESULT_FAILED, 45 MBEDTLS_TEST_RESULT_SKIPPED 46 } mbedtls_test_result_t; 47 48 typedef struct { 49 mbedtls_test_result_t result; 50 const char *test; 51 const char *filename; 52 int line_no; 53 unsigned long step; 54 char line1[76]; 55 char line2[76]; 56 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 57 const char *mutex_usage_error; 58 #endif 59 } 60 mbedtls_test_info_t; 61 extern mbedtls_test_info_t mbedtls_test_info; 62 63 int mbedtls_test_platform_setup(void); 64 void mbedtls_test_platform_teardown(void); 65 66 /** 67 * \brief Record the current test case as a failure. 68 * 69 * This function can be called directly however it is usually 70 * called via macros such as TEST_ASSERT, TEST_EQUAL, 71 * PSA_ASSERT, etc... 72 * 73 * \note If the test case was already marked as failed, calling 74 * `mbedtls_test_fail( )` again will not overwrite any 75 * previous information about the failure. 76 * 77 * \param test Description of the failure or assertion that failed. This 78 * MUST be a string literal. 79 * \param line_no Line number where the failure originated. 80 * \param filename Filename where the failure originated. 81 */ 82 void mbedtls_test_fail(const char *test, int line_no, const char *filename); 83 84 /** 85 * \brief Record the current test case as skipped. 86 * 87 * This function can be called directly however it is usually 88 * called via the TEST_ASSUME macro. 89 * 90 * \param test Description of the assumption that caused the test case to 91 * be skipped. This MUST be a string literal. 92 * \param line_no Line number where the test case was skipped. 93 * \param filename Filename where the test case was skipped. 94 */ 95 void mbedtls_test_skip(const char *test, int line_no, const char *filename); 96 97 /** 98 * \brief Set the test step number for failure reports. 99 * 100 * Call this function to display "step NNN" in addition to the 101 * line number and file name if a test fails. Typically the "step 102 * number" is the index of a for loop but it can be whatever you 103 * want. 104 * 105 * \param step The step number to report. 106 */ 107 void mbedtls_test_set_step(unsigned long step); 108 109 /** 110 * \brief Reset mbedtls_test_info to a ready/starting state. 111 */ 112 void mbedtls_test_info_reset(void); 113 114 /** 115 * \brief Record the current test case as a failure if two integers 116 * have a different value. 117 * 118 * This function is usually called via the macro 119 * #TEST_EQUAL. 120 * 121 * \param test Description of the failure or assertion that failed. This 122 * MUST be a string literal. This normally has the form 123 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1 124 * and EXPR2 has the value \p value2. 125 * \param line_no Line number where the failure originated. 126 * \param filename Filename where the failure originated. 127 * \param value1 The first value to compare. 128 * \param value2 The second value to compare. 129 * 130 * \return \c 1 if the values are equal, otherwise \c 0. 131 */ 132 int mbedtls_test_equal(const char *test, int line_no, const char *filename, 133 unsigned long long value1, unsigned long long value2); 134 135 /** 136 * \brief Record the current test case as a failure based 137 * on comparing two unsigned integers. 138 * 139 * This function is usually called via the macro 140 * #TEST_LE_U. 141 * 142 * \param test Description of the failure or assertion that failed. This 143 * MUST be a string literal. This normally has the form 144 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 145 * and EXPR2 has the value \p value2. 146 * \param line_no Line number where the failure originated. 147 * \param filename Filename where the failure originated. 148 * \param value1 The first value to compare. 149 * \param value2 The second value to compare. 150 * 151 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 152 */ 153 int mbedtls_test_le_u(const char *test, int line_no, const char *filename, 154 unsigned long long value1, unsigned long long value2); 155 156 /** 157 * \brief Record the current test case as a failure based 158 * on comparing two signed integers. 159 * 160 * This function is usually called via the macro 161 * #TEST_LE_S. 162 * 163 * \param test Description of the failure or assertion that failed. This 164 * MUST be a string literal. This normally has the form 165 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 166 * and EXPR2 has the value \p value2. 167 * \param line_no Line number where the failure originated. 168 * \param filename Filename where the failure originated. 169 * \param value1 The first value to compare. 170 * \param value2 The second value to compare. 171 * 172 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 173 */ 174 int mbedtls_test_le_s(const char *test, int line_no, const char *filename, 175 long long value1, long long value2); 176 177 /** 178 * \brief This function decodes the hexadecimal representation of 179 * data. 180 * 181 * \note The output buffer can be the same as the input buffer. For 182 * any other overlapping of the input and output buffers, the 183 * behavior is undefined. 184 * 185 * \param obuf Output buffer. 186 * \param obufmax Size in number of bytes of \p obuf. 187 * \param ibuf Input buffer. 188 * \param len The number of unsigned char written in \p obuf. This must 189 * not be \c NULL. 190 * 191 * \return \c 0 on success. 192 * \return \c -1 if the output buffer is too small or the input string 193 * is not a valid hexadecimal representation. 194 */ 195 int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax, 196 const char *ibuf, size_t *len); 197 198 void mbedtls_test_hexify(unsigned char *obuf, 199 const unsigned char *ibuf, 200 int len); 201 202 /** 203 * Allocate and zeroize a buffer. 204 * 205 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 206 * 207 * For convenience, dies if allocation fails. 208 */ 209 unsigned char *mbedtls_test_zero_alloc(size_t len); 210 211 /** 212 * Allocate and fill a buffer from hex data. 213 * 214 * The buffer is sized exactly as needed. This allows to detect buffer 215 * overruns (including overreads) when running the test suite under valgrind. 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_unhexify_alloc(const char *ibuf, size_t *olen); 222 223 int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b, 224 uint32_t a_len, uint32_t b_len); 225 226 #if defined(MBEDTLS_CHECK_PARAMS) 227 228 typedef struct { 229 const char *failure_condition; 230 const char *file; 231 int line; 232 } 233 mbedtls_test_param_failed_location_record_t; 234 235 /** 236 * \brief Get the location record of the last call to 237 * mbedtls_test_param_failed(). 238 * 239 * \note The call expectation is set up and active until the next call to 240 * mbedtls_test_param_failed_check_expected_call() or 241 * mbedtls_param_failed() that cancels it. 242 */ 243 void mbedtls_test_param_failed_get_location_record( 244 mbedtls_test_param_failed_location_record_t *location_record); 245 246 /** 247 * \brief State that a call to mbedtls_param_failed() is expected. 248 * 249 * \note The call expectation is set up and active until the next call to 250 * mbedtls_test_param_failed_check_expected_call() or 251 * mbedtls_param_failed that cancel it. 252 */ 253 void mbedtls_test_param_failed_expect_call(void); 254 255 /** 256 * \brief Check whether mbedtls_param_failed() has been called as expected. 257 * 258 * \note Check whether mbedtls_param_failed() has been called between the 259 * last call to mbedtls_test_param_failed_expect_call() and the call 260 * to this function. 261 * 262 * \return \c 0 Since the last call to mbedtls_param_failed_expect_call(), 263 * mbedtls_param_failed() has been called. 264 * \c -1 Otherwise. 265 */ 266 int mbedtls_test_param_failed_check_expected_call(void); 267 268 /** 269 * \brief Get the address of the object of type jmp_buf holding the execution 270 * state information used by mbedtls_param_failed() to do a long jump. 271 * 272 * \note If a call to mbedtls_param_failed() is not expected in the sense 273 * that there is no call to mbedtls_test_param_failed_expect_call() 274 * preceding it, then mbedtls_param_failed() will try to restore the 275 * execution to the state stored in the jmp_buf object whose address 276 * is returned by the present function. 277 * 278 * \note This function is intended to provide the parameter of the 279 * setjmp() function to set-up where mbedtls_param_failed() should 280 * long-jump if it has to. It is foreseen to be used as: 281 * 282 * setjmp( mbedtls_test_param_failed_get_state_buf() ). 283 * 284 * \note The type of the returned value is not jmp_buf as jmp_buf is an 285 * an array type (C specification) and a function cannot return an 286 * array type. 287 * 288 * \note The type of the returned value is not jmp_buf* as then the return 289 * value couldn't be used by setjmp(), as its parameter's type is 290 * jmp_buf. 291 * 292 * \return Address of the object of type jmp_buf holding the execution state 293 * information used by mbedtls_param_failed() to do a long jump. 294 */ 295 void *mbedtls_test_param_failed_get_state_buf(void); 296 297 /** 298 * \brief Reset the execution state used by mbedtls_param_failed() to do a 299 * long jump. 300 * 301 * \note If a call to mbedtls_param_failed() is not expected in the sense 302 * that there is no call to mbedtls_test_param_failed_expect_call() 303 * preceding it, then mbedtls_param_failed() will try to restore the 304 * execution state that this function reset. 305 * 306 * \note It is recommended to reset the execution state when the state 307 * is not relevant anymore. That way an unexpected call to 308 * mbedtls_param_failed() will not trigger a long jump with 309 * undefined behavior but rather a long jump that will rather fault. 310 */ 311 void mbedtls_test_param_failed_reset_state(void); 312 #endif /* MBEDTLS_CHECK_PARAMS */ 313 314 #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 315 #include "test/fake_external_rng_for_test.h" 316 #endif 317 318 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 319 /** Permanently activate the mutex usage verification framework. See 320 * threading_helpers.c for information. */ 321 void mbedtls_test_mutex_usage_init(void); 322 323 /** Call this function after executing a test case to check for mutex usage 324 * errors. */ 325 void mbedtls_test_mutex_usage_check(void); 326 #endif /* MBEDTLS_TEST_MUTEX_USAGE */ 327 328 #if defined(MBEDTLS_TEST_HOOKS) 329 /** 330 * \brief Check that only a pure high-level error code is being combined with 331 * a pure low-level error code as otherwise the resultant error code 332 * would be corrupted. 333 * 334 * \note Both high-level and low-level error codes cannot be greater than 335 * zero however can be zero. If one error code is zero then the 336 * other error code is returned even if both codes are zero. 337 * 338 * \note If the check fails, fail the test currently being run. 339 */ 340 void mbedtls_test_err_add_check(int high, int low, 341 const char *file, int line); 342 #endif 343 344 #if defined(MBEDTLS_BIGNUM_C) 345 /** Read an MPI from a hexadecimal string. 346 * 347 * Like mbedtls_mpi_read_string(), but with tighter guarantees around 348 * edge cases. 349 * 350 * - This function guarantees that if \p s begins with '-' then the sign 351 * bit of the result will be negative, even if the value is 0. 352 * When this function encounters such a "negative 0", it 353 * increments #mbedtls_test_case_uses_negative_0. 354 * - The size of the result is exactly the minimum number of limbs needed 355 * to fit the digits in the input. In particular, this function constructs 356 * a bignum with 0 limbs for an empty string, and a bignum with leading 0 357 * limbs if the string has sufficiently many leading 0 digits. 358 * This is important so that the "0 (null)" and "0 (1 limb)" and 359 * "leading zeros" test cases do what they claim. 360 * 361 * \param[out] X The MPI object to populate. It must be initialized. 362 * \param[in] s The null-terminated hexadecimal string to read from. 363 * 364 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 365 */ 366 int mbedtls_test_read_mpi(mbedtls_mpi *X, const char *s); 367 368 /** Nonzero if the current test case had an input parsed with 369 * mbedtls_test_read_mpi() that is a negative 0 (`"-"`, `"-0"`, `"-00"`, etc., 370 * constructing a result with the sign bit set to -1 and the value being 371 * all-limbs-0, which is not a valid representation in #mbedtls_mpi but is 372 * tested for robustness). 373 */ 374 extern unsigned mbedtls_test_case_uses_negative_0; 375 #endif /* MBEDTLS_BIGNUM_C */ 376 377 #endif /* TEST_HELPERS_H */ 378