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 #if defined(MBEDTLS_PLATFORM_C) 41 #include "mbedtls/platform.h" 42 #else 43 #include <stdio.h> 44 #define mbedtls_fprintf fprintf 45 #define mbedtls_snprintf snprintf 46 #define mbedtls_calloc calloc 47 #define mbedtls_free free 48 #define mbedtls_exit exit 49 #define mbedtls_time time 50 #define mbedtls_time_t time_t 51 #define MBEDTLS_EXIT_SUCCESS EXIT_SUCCESS 52 #define MBEDTLS_EXIT_FAILURE EXIT_FAILURE 53 #endif 54 55 #include <stddef.h> 56 #include <stdint.h> 57 58 #if defined(MBEDTLS_BIGNUM_C) 59 #include "mbedtls/bignum.h" 60 #endif 61 62 typedef enum 63 { 64 MBEDTLS_TEST_RESULT_SUCCESS = 0, 65 MBEDTLS_TEST_RESULT_FAILED, 66 MBEDTLS_TEST_RESULT_SKIPPED 67 } mbedtls_test_result_t; 68 69 typedef struct 70 { 71 mbedtls_test_result_t result; 72 const char *test; 73 const char *filename; 74 int line_no; 75 unsigned long step; 76 char line1[76]; 77 char line2[76]; 78 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 79 const char *mutex_usage_error; 80 #endif 81 } 82 mbedtls_test_info_t; 83 extern mbedtls_test_info_t mbedtls_test_info; 84 85 int mbedtls_test_platform_setup( void ); 86 void mbedtls_test_platform_teardown( void ); 87 88 /** 89 * \brief Record the current test case as a failure. 90 * 91 * This function can be called directly however it is usually 92 * called via macros such as TEST_ASSERT, TEST_EQUAL, 93 * PSA_ASSERT, etc... 94 * 95 * \note If the test case was already marked as failed, calling 96 * `mbedtls_test_fail( )` again will not overwrite any 97 * previous information about the failure. 98 * 99 * \param test Description of the failure or assertion that failed. This 100 * MUST be a string literal. 101 * \param line_no Line number where the failure originated. 102 * \param filename Filename where the failure originated. 103 */ 104 void mbedtls_test_fail( const char *test, int line_no, const char* filename ); 105 106 /** 107 * \brief Record the current test case as skipped. 108 * 109 * This function can be called directly however it is usually 110 * called via the TEST_ASSUME macro. 111 * 112 * \param test Description of the assumption that caused the test case to 113 * be skipped. This MUST be a string literal. 114 * \param line_no Line number where the test case was skipped. 115 * \param filename Filename where the test case was skipped. 116 */ 117 void mbedtls_test_skip( const char *test, int line_no, const char* filename ); 118 119 /** 120 * \brief Set the test step number for failure reports. 121 * 122 * Call this function to display "step NNN" in addition to the 123 * line number and file name if a test fails. Typically the "step 124 * number" is the index of a for loop but it can be whatever you 125 * want. 126 * 127 * \param step The step number to report. 128 */ 129 void mbedtls_test_set_step( unsigned long step ); 130 131 /** 132 * \brief Reset mbedtls_test_info to a ready/starting state. 133 */ 134 void mbedtls_test_info_reset( void ); 135 136 /** 137 * \brief Record the current test case as a failure if two integers 138 * have a different value. 139 * 140 * This function is usually called via the macro 141 * #TEST_EQUAL. 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 the values are equal, otherwise \c 0. 153 */ 154 int mbedtls_test_equal( const char *test, int line_no, const char* filename, 155 unsigned long long value1, unsigned long long value2 ); 156 157 /** 158 * \brief This function decodes the hexadecimal representation of 159 * data. 160 * 161 * \note The output buffer can be the same as the input buffer. For 162 * any other overlapping of the input and output buffers, the 163 * behavior is undefined. 164 * 165 * \param obuf Output buffer. 166 * \param obufmax Size in number of bytes of \p obuf. 167 * \param ibuf Input buffer. 168 * \param len The number of unsigned char written in \p obuf. This must 169 * not be \c NULL. 170 * 171 * \return \c 0 on success. 172 * \return \c -1 if the output buffer is too small or the input string 173 * is not a valid hexadecimal representation. 174 */ 175 int mbedtls_test_unhexify( unsigned char *obuf, size_t obufmax, 176 const char *ibuf, size_t *len ); 177 178 void mbedtls_test_hexify( unsigned char *obuf, 179 const unsigned char *ibuf, 180 int len ); 181 182 /** 183 * Allocate and zeroize a buffer. 184 * 185 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 186 * 187 * For convenience, dies if allocation fails. 188 */ 189 unsigned char *mbedtls_test_zero_alloc( size_t len ); 190 191 /** 192 * Allocate and fill a buffer from hex data. 193 * 194 * The buffer is sized exactly as needed. This allows to detect buffer 195 * overruns (including overreads) when running the test suite under valgrind. 196 * 197 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. 198 * 199 * For convenience, dies if allocation fails. 200 */ 201 unsigned char *mbedtls_test_unhexify_alloc( const char *ibuf, size_t *olen ); 202 203 int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b, 204 uint32_t a_len, uint32_t b_len ); 205 206 #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) 207 #include "test/fake_external_rng_for_test.h" 208 #endif 209 210 #if defined(MBEDTLS_TEST_MUTEX_USAGE) 211 /** Permanently activate the mutex usage verification framework. See 212 * threading_helpers.c for information. */ 213 void mbedtls_test_mutex_usage_init( void ); 214 215 /** Call this function after executing a test case to check for mutex usage 216 * errors. */ 217 void mbedtls_test_mutex_usage_check( void ); 218 #endif /* MBEDTLS_TEST_MUTEX_USAGE */ 219 220 #if defined(MBEDTLS_TEST_HOOKS) 221 /** 222 * \brief Check that only a pure high-level error code is being combined with 223 * a pure low-level error code as otherwise the resultant error code 224 * would be corrupted. 225 * 226 * \note Both high-level and low-level error codes cannot be greater than 227 * zero however can be zero. If one error code is zero then the 228 * other error code is returned even if both codes are zero. 229 * 230 * \note If the check fails, fail the test currently being run. 231 */ 232 void mbedtls_test_err_add_check( int high, int low, 233 const char *file, int line); 234 #endif 235 236 #if defined(MBEDTLS_BIGNUM_C) 237 /** Read an MPI from a string. 238 * 239 * Like mbedtls_mpi_read_string(), but size the resulting bignum based 240 * on the number of digits in the string. In particular, construct a 241 * bignum with 0 limbs for an empty string, and a bignum with leading 0 242 * limbs if the string has sufficiently many leading 0 digits. 243 * 244 * This is important so that the "0 (null)" and "0 (1 limb)" and 245 * "leading zeros" test cases do what they claim. 246 * 247 * \param[out] X The MPI object to populate. It must be initialized. 248 * \param radix The radix (2 to 16). 249 * \param[in] s The null-terminated string to read from. 250 * 251 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 252 */ 253 /* Since the library has exactly the desired behavior, this is trivial. */ 254 int mbedtls_test_read_mpi( mbedtls_mpi *X, int radix, const char *s ); 255 #endif /* MBEDTLS_BIGNUM_C */ 256 257 #endif /* TEST_HELPERS_H */ 258