Ronald Cron | b6d6d4c | 2020-06-03 10:11:18 +0200 | [diff] [blame] | 1 | /** |
| 2 | * \file helpers.h |
| 3 | * |
| 4 | * \brief This file contains the prototypes of helper functions for the |
| 5 | * purpose of testing. |
| 6 | */ |
| 7 | |
Bence Szépkúti | 8697465 | 2020-06-15 11:59:37 +0200 | [diff] [blame] | 8 | /* |
Bence Szépkúti | 1e14827 | 2020-08-07 13:07:28 +0200 | [diff] [blame] | 9 | * Copyright The Mbed TLS Contributors |
Ronald Cron | b6d6d4c | 2020-06-03 10:11:18 +0200 | [diff] [blame] | 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. |
Ronald Cron | b6d6d4c | 2020-06-03 10:11:18 +0200 | [diff] [blame] | 23 | */ |
| 24 | |
| 25 | #ifndef TEST_HELPERS_H |
| 26 | #define TEST_HELPERS_H |
| 27 | |
| 28 | #if !defined(MBEDTLS_CONFIG_FILE) |
| 29 | #include "mbedtls/config.h" |
| 30 | #else |
| 31 | #include MBEDTLS_CONFIG_FILE |
| 32 | #endif |
| 33 | |
Gilles Peskine | 2a4c598 | 2021-01-29 21:18:09 +0100 | [diff] [blame] | 34 | #if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \ |
| 35 | defined(MBEDTLS_TEST_HOOKS) |
| 36 | #define MBEDTLS_TEST_MUTEX_USAGE |
| 37 | #endif |
| 38 | |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 39 | #if defined(MBEDTLS_PLATFORM_C) |
| 40 | #include "mbedtls/platform.h" |
| 41 | #else |
| 42 | #include <stdio.h> |
| 43 | #define mbedtls_fprintf fprintf |
| 44 | #define mbedtls_snprintf snprintf |
| 45 | #define mbedtls_calloc calloc |
| 46 | #define mbedtls_free free |
| 47 | #define mbedtls_exit exit |
| 48 | #define mbedtls_time time |
| 49 | #define mbedtls_time_t time_t |
| 50 | #define MBEDTLS_EXIT_SUCCESS EXIT_SUCCESS |
| 51 | #define MBEDTLS_EXIT_FAILURE EXIT_FAILURE |
| 52 | #endif |
| 53 | |
| 54 | #include <stddef.h> |
| 55 | #include <stdint.h> |
| 56 | |
Gilles Peskine | db47971 | 2021-06-11 14:13:53 +0200 | [diff] [blame^] | 57 | #if defined(MBEDTLS_BIGNUM_C) |
| 58 | #include "mbedtls/bignum.h" |
| 59 | #endif |
| 60 | |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 61 | typedef enum |
| 62 | { |
Chris Jones | e60e2ae | 2021-01-20 17:51:47 +0000 | [diff] [blame] | 63 | MBEDTLS_TEST_RESULT_SUCCESS = 0, |
| 64 | MBEDTLS_TEST_RESULT_FAILED, |
| 65 | MBEDTLS_TEST_RESULT_SKIPPED |
| 66 | } mbedtls_test_result_t; |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 67 | |
| 68 | typedef struct |
| 69 | { |
Chris Jones | e60e2ae | 2021-01-20 17:51:47 +0000 | [diff] [blame] | 70 | mbedtls_test_result_t result; |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 71 | const char *test; |
| 72 | const char *filename; |
| 73 | int line_no; |
| 74 | unsigned long step; |
Gilles Peskine | 2a4c598 | 2021-01-29 21:18:09 +0100 | [diff] [blame] | 75 | #if defined(MBEDTLS_TEST_MUTEX_USAGE) |
| 76 | const char *mutex_usage_error; |
| 77 | #endif |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 78 | } |
Chris Jones | e60e2ae | 2021-01-20 17:51:47 +0000 | [diff] [blame] | 79 | mbedtls_test_info_t; |
| 80 | extern mbedtls_test_info_t mbedtls_test_info; |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 81 | |
Ronald Cron | e9c09f1 | 2020-06-08 16:44:58 +0200 | [diff] [blame] | 82 | int mbedtls_test_platform_setup( void ); |
| 83 | void mbedtls_test_platform_teardown( void ); |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 84 | |
Ronald Cron | a0c2539 | 2020-06-18 10:10:46 +0200 | [diff] [blame] | 85 | /** |
Chris Jones | 39ddb0a | 2021-02-03 16:15:00 +0000 | [diff] [blame] | 86 | * \brief Record the current test case as a failure. |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 87 | * |
Chris Jones | 39ddb0a | 2021-02-03 16:15:00 +0000 | [diff] [blame] | 88 | * This function can be called directly however it is usually |
| 89 | * called via macros such as TEST_ASSERT, TEST_EQUAL, |
| 90 | * PSA_ASSERT, etc... |
| 91 | * |
| 92 | * \note If the test case was already marked as failed, calling |
| 93 | * `mbedtls_test_fail( )` again will not overwrite any |
| 94 | * previous information about the failure. |
| 95 | * |
| 96 | * \param test Description of the failure or assertion that failed. This |
| 97 | * MUST be a string literal. |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 98 | * \param line_no Line number where the failure originated. |
| 99 | * \param filename Filename where the failure originated. |
| 100 | */ |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 101 | void mbedtls_test_fail( const char *test, int line_no, const char* filename ); |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 102 | |
| 103 | /** |
Chris Jones | 39ddb0a | 2021-02-03 16:15:00 +0000 | [diff] [blame] | 104 | * \brief Record the current test case as skipped. |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 105 | * |
Chris Jones | 39ddb0a | 2021-02-03 16:15:00 +0000 | [diff] [blame] | 106 | * This function can be called directly however it is usually |
| 107 | * called via the TEST_ASSUME macro. |
| 108 | * |
| 109 | * \param test Description of the assumption that caused the test case to |
| 110 | * be skipped. This MUST be a string literal. |
| 111 | * \param line_no Line number where the test case was skipped. |
| 112 | * \param filename Filename where the test case was skipped. |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 113 | */ |
Chris Jones | a5ab765 | 2021-02-02 16:20:45 +0000 | [diff] [blame] | 114 | void mbedtls_test_skip( const char *test, int line_no, const char* filename ); |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 115 | |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 116 | /** |
| 117 | * \brief Set the test step number for failure reports. |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 118 | * |
Chris Jones | 39ddb0a | 2021-02-03 16:15:00 +0000 | [diff] [blame] | 119 | * Call this function to display "step NNN" in addition to the |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 120 | * line number and file name if a test fails. Typically the "step |
| 121 | * number" is the index of a for loop but it can be whatever you |
| 122 | * want. |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 123 | * |
| 124 | * \param step The step number to report. |
| 125 | */ |
| 126 | void mbedtls_test_set_step( unsigned long step ); |
| 127 | |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 128 | /** |
| 129 | * \brief Reset mbedtls_test_info to a ready/starting state. |
Chris Jones | 567e0ad | 2021-02-03 12:07:01 +0000 | [diff] [blame] | 130 | */ |
Chris Jones | a5ab765 | 2021-02-02 16:20:45 +0000 | [diff] [blame] | 131 | void mbedtls_test_info_reset( void ); |
Chris Jones | 9634bb1 | 2021-01-20 15:56:42 +0000 | [diff] [blame] | 132 | |
Ronald Cron | a0c2539 | 2020-06-18 10:10:46 +0200 | [diff] [blame] | 133 | /** |
Ronald Cron | ab500cb | 2020-07-01 17:09:10 +0200 | [diff] [blame] | 134 | * \brief This function decodes the hexadecimal representation of |
| 135 | * data. |
Ronald Cron | a0c2539 | 2020-06-18 10:10:46 +0200 | [diff] [blame] | 136 | * |
| 137 | * \note The output buffer can be the same as the input buffer. For |
| 138 | * any other overlapping of the input and output buffers, the |
| 139 | * behavior is undefined. |
| 140 | * |
| 141 | * \param obuf Output buffer. |
| 142 | * \param obufmax Size in number of bytes of \p obuf. |
| 143 | * \param ibuf Input buffer. |
| 144 | * \param len The number of unsigned char written in \p obuf. This must |
| 145 | * not be \c NULL. |
| 146 | * |
| 147 | * \return \c 0 on success. |
| 148 | * \return \c -1 if the output buffer is too small or the input string |
Ronald Cron | ab500cb | 2020-07-01 17:09:10 +0200 | [diff] [blame] | 149 | * is not a valid hexadecimal representation. |
Ronald Cron | a0c2539 | 2020-06-18 10:10:46 +0200 | [diff] [blame] | 150 | */ |
| 151 | int mbedtls_test_unhexify( unsigned char *obuf, size_t obufmax, |
| 152 | const char *ibuf, size_t *len ); |
| 153 | |
Ronald Cron | 72d628f | 2020-06-08 17:05:57 +0200 | [diff] [blame] | 154 | void mbedtls_test_hexify( unsigned char *obuf, |
| 155 | const unsigned char *ibuf, |
| 156 | int len ); |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 157 | |
| 158 | /** |
| 159 | * Allocate and zeroize a buffer. |
| 160 | * |
| 161 | * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. |
| 162 | * |
| 163 | * For convenience, dies if allocation fails. |
| 164 | */ |
Ronald Cron | 690f3eb | 2020-06-10 10:42:18 +0200 | [diff] [blame] | 165 | unsigned char *mbedtls_test_zero_alloc( size_t len ); |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 166 | |
| 167 | /** |
| 168 | * Allocate and fill a buffer from hex data. |
| 169 | * |
| 170 | * The buffer is sized exactly as needed. This allows to detect buffer |
| 171 | * overruns (including overreads) when running the test suite under valgrind. |
| 172 | * |
| 173 | * If the size if zero, a pointer to a zeroized 1-byte buffer is returned. |
| 174 | * |
| 175 | * For convenience, dies if allocation fails. |
| 176 | */ |
Ronald Cron | a256c70 | 2020-06-10 10:53:11 +0200 | [diff] [blame] | 177 | unsigned char *mbedtls_test_unhexify_alloc( const char *ibuf, size_t *olen ); |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 178 | |
Ronald Cron | de70b16 | 2020-06-10 11:03:08 +0200 | [diff] [blame] | 179 | int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b, |
| 180 | uint32_t a_len, uint32_t b_len ); |
Ronald Cron | f40529d | 2020-06-09 16:27:37 +0200 | [diff] [blame] | 181 | |
Ronald Cron | a123614 | 2020-07-01 16:01:21 +0200 | [diff] [blame] | 182 | #if defined(MBEDTLS_CHECK_PARAMS) |
| 183 | |
| 184 | typedef struct |
| 185 | { |
| 186 | const char *failure_condition; |
| 187 | const char *file; |
| 188 | int line; |
| 189 | } |
| 190 | mbedtls_test_param_failed_location_record_t; |
| 191 | |
| 192 | /** |
| 193 | * \brief Get the location record of the last call to |
| 194 | * mbedtls_test_param_failed(). |
| 195 | * |
| 196 | * \note The call expectation is set up and active until the next call to |
| 197 | * mbedtls_test_param_failed_check_expected_call() or |
| 198 | * mbedtls_param_failed() that cancels it. |
| 199 | */ |
| 200 | void mbedtls_test_param_failed_get_location_record( |
| 201 | mbedtls_test_param_failed_location_record_t *location_record ); |
| 202 | |
| 203 | /** |
| 204 | * \brief State that a call to mbedtls_param_failed() is expected. |
| 205 | * |
| 206 | * \note The call expectation is set up and active until the next call to |
| 207 | * mbedtls_test_param_failed_check_expected_call() or |
| 208 | * mbedtls_param_failed that cancel it. |
| 209 | */ |
| 210 | void mbedtls_test_param_failed_expect_call( void ); |
| 211 | |
| 212 | /** |
| 213 | * \brief Check whether mbedtls_param_failed() has been called as expected. |
| 214 | * |
| 215 | * \note Check whether mbedtls_param_failed() has been called between the |
| 216 | * last call to mbedtls_test_param_failed_expect_call() and the call |
| 217 | * to this function. |
| 218 | * |
| 219 | * \return \c 0 Since the last call to mbedtls_param_failed_expect_call(), |
| 220 | * mbedtls_param_failed() has been called. |
| 221 | * \c -1 Otherwise. |
| 222 | */ |
| 223 | int mbedtls_test_param_failed_check_expected_call( void ); |
| 224 | |
| 225 | /** |
Ronald Cron | bf4f408 | 2020-09-25 10:45:06 +0200 | [diff] [blame] | 226 | * \brief Get the address of the object of type jmp_buf holding the execution |
Ronald Cron | a123614 | 2020-07-01 16:01:21 +0200 | [diff] [blame] | 227 | * state information used by mbedtls_param_failed() to do a long jump. |
| 228 | * |
| 229 | * \note If a call to mbedtls_param_failed() is not expected in the sense |
| 230 | * that there is no call to mbedtls_test_param_failed_expect_call() |
| 231 | * preceding it, then mbedtls_param_failed() will try to restore the |
| 232 | * execution to the state stored in the jmp_buf object whose address |
| 233 | * is returned by the present function. |
| 234 | * |
Ronald Cron | bf4f408 | 2020-09-25 10:45:06 +0200 | [diff] [blame] | 235 | * \note This function is intended to provide the parameter of the |
| 236 | * setjmp() function to set-up where mbedtls_param_failed() should |
| 237 | * long-jump if it has to. It is foreseen to be used as: |
| 238 | * |
| 239 | * setjmp( mbedtls_test_param_failed_get_state_buf() ). |
| 240 | * |
| 241 | * \note The type of the returned value is not jmp_buf as jmp_buf is an |
| 242 | * an array type (C specification) and a function cannot return an |
| 243 | * array type. |
| 244 | * |
| 245 | * \note The type of the returned value is not jmp_buf* as then the return |
| 246 | * value couldn't be used by setjmp(), as its parameter's type is |
| 247 | * jmp_buf. |
Ronald Cron | a123614 | 2020-07-01 16:01:21 +0200 | [diff] [blame] | 248 | * |
| 249 | * \return Address of the object of type jmp_buf holding the execution state |
| 250 | * information used by mbedtls_param_failed() to do a long jump. |
| 251 | */ |
| 252 | void* mbedtls_test_param_failed_get_state_buf( void ); |
| 253 | |
| 254 | /** |
| 255 | * \brief Reset the execution state used by mbedtls_param_failed() to do a |
| 256 | * long jump. |
| 257 | * |
| 258 | * \note If a call to mbedtls_param_failed() is not expected in the sense |
| 259 | * that there is no call to mbedtls_test_param_failed_expect_call() |
| 260 | * preceding it, then mbedtls_param_failed() will try to restore the |
| 261 | * execution state that this function reset. |
| 262 | * |
| 263 | * \note It is recommended to reset the execution state when the state |
| 264 | * is not relevant anymore. That way an unexpected call to |
| 265 | * mbedtls_param_failed() will not trigger a long jump with |
| 266 | * undefined behavior but rather a long jump that will rather fault. |
| 267 | */ |
| 268 | void mbedtls_test_param_failed_reset_state( void ); |
| 269 | #endif /* MBEDTLS_CHECK_PARAMS */ |
| 270 | |
Gilles Peskine | 1dc19ff | 2021-02-08 20:59:39 +0100 | [diff] [blame] | 271 | #if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG) |
Gilles Peskine | 1af872d | 2021-01-20 20:02:01 +0100 | [diff] [blame] | 272 | #include "test/fake_external_rng_for_test.h" |
| 273 | #endif |
| 274 | |
Gilles Peskine | 2a4c598 | 2021-01-29 21:18:09 +0100 | [diff] [blame] | 275 | #if defined(MBEDTLS_TEST_MUTEX_USAGE) |
Gilles Peskine | 1061ec6 | 2021-01-29 21:17:11 +0100 | [diff] [blame] | 276 | /** Permanently activate the mutex usage verification framework. See |
| 277 | * threading_helpers.c for information. */ |
| 278 | void mbedtls_test_mutex_usage_init( void ); |
Gilles Peskine | 2a4c598 | 2021-01-29 21:18:09 +0100 | [diff] [blame] | 279 | |
| 280 | /** Call this function after executing a test case to check for mutex usage |
| 281 | * errors. */ |
| 282 | void mbedtls_test_mutex_usage_check( void ); |
Gilles Peskine | 1061ec6 | 2021-01-29 21:17:11 +0100 | [diff] [blame] | 283 | #endif /* MBEDTLS_TEST_MUTEX_USAGE */ |
| 284 | |
Chris Jones | 96ae73b | 2021-01-08 17:04:59 +0000 | [diff] [blame] | 285 | #if defined(MBEDTLS_TEST_HOOKS) |
| 286 | /** |
Chris Jones | 3f613c1 | 2021-03-31 09:34:22 +0100 | [diff] [blame] | 287 | * \brief Check that only a pure high-level error code is being combined with |
| 288 | * a pure low-level error code as otherwise the resultant error code |
Chris Jones | 5e8805a | 2021-01-12 15:21:57 +0000 | [diff] [blame] | 289 | * would be corrupted. |
Chris Jones | 3f613c1 | 2021-03-31 09:34:22 +0100 | [diff] [blame] | 290 | * |
| 291 | * \note Both high-level and low-level error codes cannot be greater than |
| 292 | * zero however can be zero. If one error code is zero then the |
| 293 | * other error code is returned even if both codes are zero. |
| 294 | * |
| 295 | * \note If the check fails, fail the test currently being run. |
Chris Jones | 96ae73b | 2021-01-08 17:04:59 +0000 | [diff] [blame] | 296 | */ |
| 297 | void mbedtls_test_err_add_check( int high, int low, |
| 298 | const char *file, int line); |
| 299 | #endif |
| 300 | |
Gilles Peskine | db47971 | 2021-06-11 14:13:53 +0200 | [diff] [blame^] | 301 | #if defined(MBEDTLS_BIGNUM_C) |
| 302 | /** Read an MPI from a string. |
| 303 | * |
| 304 | * Like mbedtls_mpi_read_string(), but size the resulting bignum based |
| 305 | * on the number of digits in the string. In particular, construct a |
| 306 | * bignum with 0 limbs for an empty string, and a bignum with leading 0 |
| 307 | * limbs if the string has sufficiently many leading 0 digits. |
| 308 | * |
| 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 radix The radix (2 to 16). |
| 314 | * \param[in] s The null-terminated string to read from. |
| 315 | * |
| 316 | * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. |
| 317 | */ |
| 318 | /* Since the library has exactly the desired behavior, this is trivial. */ |
| 319 | int mbedtls_test_read_mpi( mbedtls_mpi *X, int radix, const char *s ); |
| 320 | #endif /* MBEDTLS_BIGNUM_C */ |
| 321 | |
Ronald Cron | b6d6d4c | 2020-06-03 10:11:18 +0200 | [diff] [blame] | 322 | #endif /* TEST_HELPERS_H */ |