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 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); you may 13 * not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 20 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 */ 24 25 #ifndef TEST_HELPERS_H 26 #define TEST_HELPERS_H 27 28 /* Most fields of publicly available structs are private and are wrapped with 29 * MBEDTLS_PRIVATE macro. This define allows tests to access the private fields 30 * directly (without using the MBEDTLS_PRIVATE wrapper). */ 31 #define MBEDTLS_ALLOW_PRIVATE_ACCESS 32 33 #include "mbedtls/build_info.h" 34 35 #if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \ 36 defined(MBEDTLS_TEST_HOOKS) 37 #define MBEDTLS_TEST_MUTEX_USAGE 38 #endif 39 40 #include "mbedtls/platform.h" 41 42 #include <stddef.h> 43 #include <stdint.h> 44 45 #if defined(MBEDTLS_BIGNUM_C) 46 #include "mbedtls/bignum.h" 47 #endif 48 49 /** The type of test case arguments that contain binary data. */ 50 typedef struct data_tag 51 { 52 uint8_t * x; 53 uint32_t len; 54 } data_t; 55 56 typedef enum 57 { 58 MBEDTLS_TEST_RESULT_SUCCESS = 0, 59 MBEDTLS_TEST_RESULT_FAILED, 60 MBEDTLS_TEST_RESULT_SKIPPED 61 } mbedtls_test_result_t; 62 63 typedef struct 64 { 65 mbedtls_test_result_t result; 66 const char *test; 67 const char *filename; 68 int line_no; 69 unsigned long step; 70 char line1[76]; 71 char line2[76]; 72 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 73 const char *mutex_usage_error; 74 #endif 75 } 76 mbedtls_test_info_t; 77 extern mbedtls_test_info_t mbedtls_test_info; 78 79 int mbedtls_test_platform_setup( void ); 80 void mbedtls_test_platform_teardown( void ); 81 82 /** 83 * \brief Record the current test case as a failure. 84 * 85 * This function can be called directly however it is usually 86 * called via macros such as TEST_ASSERT, TEST_EQUAL, 87 * PSA_ASSERT, etc... 88 * 89 * \note If the test case was already marked as failed, calling 90 * `mbedtls_test_fail( )` again will not overwrite any 91 * previous information about the failure. 92 * 93 * \param test Description of the failure or assertion that failed. This 94 * MUST be a string literal. 95 * \param line_no Line number where the failure originated. 96 * \param filename Filename where the failure originated. 97 */ 98 void mbedtls_test_fail( const char *test, int line_no, const char* filename ); 99 100 /** 101 * \brief Record the current test case as skipped. 102 * 103 * This function can be called directly however it is usually 104 * called via the TEST_ASSUME macro. 105 * 106 * \param test Description of the assumption that caused the test case to 107 * be skipped. This MUST be a string literal. 108 * \param line_no Line number where the test case was skipped. 109 * \param filename Filename where the test case was skipped. 110 */ 111 void mbedtls_test_skip( const char *test, int line_no, const char* filename ); 112 113 /** 114 * \brief Set the test step number for failure reports. 115 * 116 * Call this function to display "step NNN" in addition to the 117 * line number and file name if a test fails. Typically the "step 118 * number" is the index of a for loop but it can be whatever you 119 * want. 120 * 121 * \param step The step number to report. 122 */ 123 void mbedtls_test_set_step( unsigned long step ); 124 125 /** 126 * \brief Reset mbedtls_test_info to a ready/starting state. 127 */ 128 void mbedtls_test_info_reset( void ); 129 130 /** 131 * \brief Record the current test case as a failure if two integers 132 * have a different value. 133 * 134 * This function is usually called via the macro 135 * #TEST_EQUAL. 136 * 137 * \param test Description of the failure or assertion that failed. This 138 * MUST be a string literal. This normally has the form 139 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1 140 * and EXPR2 has the value \p value2. 141 * \param line_no Line number where the failure originated. 142 * \param filename Filename where the failure originated. 143 * \param value1 The first value to compare. 144 * \param value2 The second value to compare. 145 * 146 * \return \c 1 if the values are equal, otherwise \c 0. 147 */ 148 int mbedtls_test_equal( const char *test, int line_no, const char* filename, 149 unsigned long long value1, unsigned long long value2 ); 150 151 /** 152 * \brief Record the current test case as a failure based 153 * on comparing two unsigned integers. 154 * 155 * This function is usually called via the macro 156 * #TEST_LE_U. 157 * 158 * \param test Description of the failure or assertion that failed. This 159 * MUST be a string literal. This normally has the form 160 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 161 * and EXPR2 has the value \p value2. 162 * \param line_no Line number where the failure originated. 163 * \param filename Filename where the failure originated. 164 * \param value1 The first value to compare. 165 * \param value2 The second value to compare. 166 * 167 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 168 */ 169 int mbedtls_test_le_u( const char *test, int line_no, const char* filename, 170 unsigned long long value1, unsigned long long value2 ); 171 172 /** 173 * \brief Record the current test case as a failure based 174 * on comparing two signed integers. 175 * 176 * This function is usually called via the macro 177 * #TEST_LE_S. 178 * 179 * \param test Description of the failure or assertion that failed. This 180 * MUST be a string literal. This normally has the form 181 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1 182 * and EXPR2 has the value \p value2. 183 * \param line_no Line number where the failure originated. 184 * \param filename Filename where the failure originated. 185 * \param value1 The first value to compare. 186 * \param value2 The second value to compare. 187 * 188 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0. 189 */ 190 int mbedtls_test_le_s( const char *test, int line_no, const char* filename, 191 long long value1, long long value2 ); 192 193 /** 194 * \brief This function decodes the hexadecimal representation of 195 * data. 196 * 197 * \note The output buffer can be the same as the input buffer. For 198 * any other overlapping of the input and output buffers, the 199 * behavior is undefined. 200 * 201 * \param obuf Output buffer. 202 * \param obufmax Size in number of bytes of \p obuf. 203 * \param ibuf Input buffer. 204 * \param len The number of unsigned char written in \p obuf. This must 205 * not be \c NULL. 206 * 207 * \return \c 0 on success. 208 * \return \c -1 if the output buffer is too small or the input string 209 * is not a valid hexadecimal representation. 210 */ 211 int mbedtls_test_unhexify( unsigned char *obuf, size_t obufmax, 212 const char *ibuf, size_t *len ); 213 214 void mbedtls_test_hexify( unsigned char *obuf, 215 const unsigned char *ibuf, 216 int len ); 217 218 /** 219 * Allocate and zeroize a buffer. 220 * 221 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 222 * 223 * For convenience, dies if allocation fails. 224 */ 225 unsigned char *mbedtls_test_zero_alloc( size_t len ); 226 227 /** 228 * Allocate and fill a buffer from hex data. 229 * 230 * The buffer is sized exactly as needed. This allows to detect buffer 231 * overruns (including overreads) when running the test suite under valgrind. 232 * 233 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 234 * 235 * For convenience, dies if allocation fails. 236 */ 237 unsigned char *mbedtls_test_unhexify_alloc( const char *ibuf, size_t *olen ); 238 239 int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b, 240 uint32_t a_len, uint32_t b_len ); 241 242 #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 243 #include "test/fake_external_rng_for_test.h" 244 #endif 245 246 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 247 /** Permanently activate the mutex usage verification framework. See 248 * threading_helpers.c for information. */ 249 void mbedtls_test_mutex_usage_init( void ); 250 251 /** Call this function after executing a test case to check for mutex usage 252 * errors. */ 253 void mbedtls_test_mutex_usage_check( void ); 254 #endif /* MBEDTLS_TEST_MUTEX_USAGE */ 255 256 #if defined(MBEDTLS_TEST_HOOKS) 257 /** 258 * \brief Check that only a pure high-level error code is being combined with 259 * a pure low-level error code as otherwise the resultant error code 260 * would be corrupted. 261 * 262 * \note Both high-level and low-level error codes cannot be greater than 263 * zero however can be zero. If one error code is zero then the 264 * other error code is returned even if both codes are zero. 265 * 266 * \note If the check fails, fail the test currently being run. 267 */ 268 void mbedtls_test_err_add_check( int high, int low, 269 const char *file, int line); 270 #endif 271 272 #if defined(MBEDTLS_BIGNUM_C) 273 /** Allocate and populate a core MPI from a test case argument. 274 * 275 * This function allocates exactly as many limbs as necessary to fit 276 * the length of the input. In other words, it preserves leading zeros. 277 * 278 * The limb array is allocated with mbedtls_calloc() and must later be 279 * freed with mbedtls_free(). 280 * 281 * \param[in,out] pX The address where a pointer to the allocated limb 282 * array will be stored. 283 * \c *pX must be null on entry. 284 * On exit, \c *pX is null on error or if the number 285 * of limbs is 0. 286 * \param[out] plimbs The address where the number of limbs will be stored. 287 * \param[in] input The test argument to read. 288 * It is interpreted as a hexadecimal representation 289 * of a non-negative integer. 290 * 291 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 292 */ 293 int mbedtls_test_read_mpi_core( mbedtls_mpi_uint **pX, size_t *plimbs, 294 const char *input ); 295 296 /** Read an MPI from a hexadecimal string. 297 * 298 * Like mbedtls_mpi_read_string(), but with tighter guarantees around 299 * edge cases. 300 * 301 * - This function guarantees that if \p s begins with '-' then the sign 302 * bit of the result will be negative, even if the value is 0. 303 * When this function encounters such a "negative 0", it 304 * increments #mbedtls_test_case_uses_negative_0. 305 * - The size of the result is exactly the minimum number of limbs needed 306 * to fit the digits in the input. In particular, this function constructs 307 * a bignum with 0 limbs for an empty string, and a bignum with leading 0 308 * limbs if the string has sufficiently many leading 0 digits. 309 * This is important so that the "0 (null)" and "0 (1 limb)" and 310 * "leading zeros" test cases do what they claim. 311 * 312 * \param[out] X The MPI object to populate. It must be initialized. 313 * \param[in] s The null-terminated hexadecimal string to read from. 314 * 315 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 316 */ 317 int mbedtls_test_read_mpi( mbedtls_mpi *X, const char *s ); 318 319 /** Nonzero if the current test case had an input parsed with 320 * mbedtls_test_read_mpi() that is a negative 0 (`"-"`, `"-0"`, `"-00"`, etc., 321 * constructing a result with the sign bit set to -1 and the value being 322 * all-limbs-0, which is not a valid representation in #mbedtls_mpi but is 323 * tested for robustness). 324 */ 325 extern unsigned mbedtls_test_case_uses_negative_0; 326 #endif /* MBEDTLS_BIGNUM_C */ 327 328 #endif /* TEST_HELPERS_H */ 329
