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