blob: 17153b7d613c82ae47773a202155c4e2b5d8fd30 [file] [log] [blame]
Ronald Cronb6d6d4c2020-06-03 10:11:18 +02001/**
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úti86974652020-06-15 11:59:37 +02008/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02009 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +000010 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Ronald Cronb6d6d4c2020-06-03 10:11:18 +020011 */
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
Gilles Peskinec3a9bdb2023-11-22 17:55:43 +010022#if defined(__SANITIZE_ADDRESS__) /* gcc -fsanitize=address */
23# define MBEDTLS_TEST_HAVE_ASAN
24#endif
25#if defined(__has_feature)
26# if __has_feature(address_sanitizer) /* clang -fsanitize=address */
27# define MBEDTLS_TEST_HAVE_ASAN
28# endif
29# if __has_feature(memory_sanitizer) /* clang -fsanitize=memory */
30# define MBEDTLS_TEST_HAVE_MSAN
31# endif
32# if __has_feature(thread_sanitizer) /* clang -fsanitize=thread */
33# define MBEDTLS_TEST_HAVE_TSAN
34# endif
35#endif
36
Gilles Peskine2a4c5982021-01-29 21:18:09 +010037#if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \
38 defined(MBEDTLS_TEST_HOOKS)
39#define MBEDTLS_TEST_MUTEX_USAGE
40#endif
41
Ronald Cronf40529d2020-06-09 16:27:37 +020042#include "mbedtls/platform.h"
Ronald Cronf40529d2020-06-09 16:27:37 +020043
44#include <stddef.h>
45#include <stdint.h>
46
Gilles Peskinedb479712021-06-11 14:13:53 +020047#if defined(MBEDTLS_BIGNUM_C)
48#include "mbedtls/bignum.h"
49#endif
50
Gilles Peskine34cb4622022-09-20 21:37:56 +020051/** The type of test case arguments that contain binary data. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010052typedef struct data_tag {
53 uint8_t *x;
Gilles Peskine34cb4622022-09-20 21:37:56 +020054 uint32_t len;
55} data_t;
56
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010057typedef enum {
Chris Jonese60e2ae2021-01-20 17:51:47 +000058 MBEDTLS_TEST_RESULT_SUCCESS = 0,
59 MBEDTLS_TEST_RESULT_FAILED,
60 MBEDTLS_TEST_RESULT_SKIPPED
61} mbedtls_test_result_t;
Chris Jones9634bb12021-01-20 15:56:42 +000062
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010063typedef struct {
Chris Jonese60e2ae2021-01-20 17:51:47 +000064 mbedtls_test_result_t result;
Chris Jones9634bb12021-01-20 15:56:42 +000065 const char *test;
66 const char *filename;
67 int line_no;
68 unsigned long step;
Gilles Peskineb4366492021-04-29 20:28:54 +020069 char line1[76];
70 char line2[76];
Gilles Peskine2a4c5982021-01-29 21:18:09 +010071#if defined(MBEDTLS_TEST_MUTEX_USAGE)
72 const char *mutex_usage_error;
73#endif
Chris Jones9634bb12021-01-20 15:56:42 +000074}
Chris Jonese60e2ae2021-01-20 17:51:47 +000075mbedtls_test_info_t;
76extern mbedtls_test_info_t mbedtls_test_info;
Chris Jones9634bb12021-01-20 15:56:42 +000077
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010078int mbedtls_test_platform_setup(void);
79void mbedtls_test_platform_teardown(void);
Ronald Cronf40529d2020-06-09 16:27:37 +020080
Ronald Crona0c25392020-06-18 10:10:46 +020081/**
Chris Jones39ddb0a2021-02-03 16:15:00 +000082 * \brief Record the current test case as a failure.
Chris Jones567e0ad2021-02-03 12:07:01 +000083 *
Chris Jones39ddb0a2021-02-03 16:15:00 +000084 * This function can be called directly however it is usually
85 * called via macros such as TEST_ASSERT, TEST_EQUAL,
86 * PSA_ASSERT, etc...
87 *
88 * \note If the test case was already marked as failed, calling
89 * `mbedtls_test_fail( )` again will not overwrite any
90 * previous information about the failure.
91 *
92 * \param test Description of the failure or assertion that failed. This
93 * MUST be a string literal.
Chris Jones567e0ad2021-02-03 12:07:01 +000094 * \param line_no Line number where the failure originated.
95 * \param filename Filename where the failure originated.
96 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010097void mbedtls_test_fail(const char *test, int line_no, const char *filename);
Chris Jones567e0ad2021-02-03 12:07:01 +000098
99/**
Chris Jones39ddb0a2021-02-03 16:15:00 +0000100 * \brief Record the current test case as skipped.
Chris Jones567e0ad2021-02-03 12:07:01 +0000101 *
Chris Jones39ddb0a2021-02-03 16:15:00 +0000102 * This function can be called directly however it is usually
103 * called via the TEST_ASSUME macro.
104 *
105 * \param test Description of the assumption that caused the test case to
106 * be skipped. This MUST be a string literal.
107 * \param line_no Line number where the test case was skipped.
108 * \param filename Filename where the test case was skipped.
Chris Jones567e0ad2021-02-03 12:07:01 +0000109 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100110void mbedtls_test_skip(const char *test, int line_no, const char *filename);
Chris Jones9634bb12021-01-20 15:56:42 +0000111
Chris Jones567e0ad2021-02-03 12:07:01 +0000112/**
113 * \brief Set the test step number for failure reports.
Chris Jones9634bb12021-01-20 15:56:42 +0000114 *
Chris Jones39ddb0a2021-02-03 16:15:00 +0000115 * Call this function to display "step NNN" in addition to the
Chris Jones567e0ad2021-02-03 12:07:01 +0000116 * line number and file name if a test fails. Typically the "step
117 * number" is the index of a for loop but it can be whatever you
118 * want.
Chris Jones9634bb12021-01-20 15:56:42 +0000119 *
120 * \param step The step number to report.
121 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100122void mbedtls_test_set_step(unsigned long step);
Chris Jones9634bb12021-01-20 15:56:42 +0000123
Chris Jones567e0ad2021-02-03 12:07:01 +0000124/**
125 * \brief Reset mbedtls_test_info to a ready/starting state.
Chris Jones567e0ad2021-02-03 12:07:01 +0000126 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100127void mbedtls_test_info_reset(void);
Chris Jones9634bb12021-01-20 15:56:42 +0000128
Ronald Crona0c25392020-06-18 10:10:46 +0200129/**
Gilles Peskineb4366492021-04-29 20:28:54 +0200130 * \brief Record the current test case as a failure if two integers
131 * have a different value.
132 *
133 * This function is usually called via the macro
134 * #TEST_EQUAL.
135 *
136 * \param test Description of the failure or assertion that failed. This
137 * MUST be a string literal. This normally has the form
138 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1
139 * and EXPR2 has the value \p value2.
140 * \param line_no Line number where the failure originated.
141 * \param filename Filename where the failure originated.
142 * \param value1 The first value to compare.
143 * \param value2 The second value to compare.
144 *
145 * \return \c 1 if the values are equal, otherwise \c 0.
146 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100147int mbedtls_test_equal(const char *test, int line_no, const char *filename,
148 unsigned long long value1, unsigned long long value2);
Gilles Peskineb4366492021-04-29 20:28:54 +0200149
150/**
Gilles Peskine063700d2022-04-13 23:59:52 +0200151 * \brief Record the current test case as a failure based
152 * on comparing two unsigned integers.
153 *
154 * This function is usually called via the macro
155 * #TEST_LE_U.
156 *
157 * \param test Description of the failure or assertion that failed. This
158 * MUST be a string literal. This normally has the form
159 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
160 * and EXPR2 has the value \p value2.
161 * \param line_no Line number where the failure originated.
162 * \param filename Filename where the failure originated.
163 * \param value1 The first value to compare.
164 * \param value2 The second value to compare.
165 *
166 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
167 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100168int mbedtls_test_le_u(const char *test, int line_no, const char *filename,
169 unsigned long long value1, unsigned long long value2);
Gilles Peskine063700d2022-04-13 23:59:52 +0200170
171/**
172 * \brief Record the current test case as a failure based
173 * on comparing two signed integers.
174 *
175 * This function is usually called via the macro
176 * #TEST_LE_S.
177 *
178 * \param test Description of the failure or assertion that failed. This
179 * MUST be a string literal. This normally has the form
180 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
181 * and EXPR2 has the value \p value2.
182 * \param line_no Line number where the failure originated.
183 * \param filename Filename where the failure originated.
184 * \param value1 The first value to compare.
185 * \param value2 The second value to compare.
186 *
187 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
188 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100189int mbedtls_test_le_s(const char *test, int line_no, const char *filename,
190 long long value1, long long value2);
Gilles Peskine063700d2022-04-13 23:59:52 +0200191
192/**
Ronald Cronab500cb2020-07-01 17:09:10 +0200193 * \brief This function decodes the hexadecimal representation of
194 * data.
Ronald Crona0c25392020-06-18 10:10:46 +0200195 *
196 * \note The output buffer can be the same as the input buffer. For
197 * any other overlapping of the input and output buffers, the
198 * behavior is undefined.
199 *
200 * \param obuf Output buffer.
201 * \param obufmax Size in number of bytes of \p obuf.
202 * \param ibuf Input buffer.
203 * \param len The number of unsigned char written in \p obuf. This must
204 * not be \c NULL.
205 *
206 * \return \c 0 on success.
207 * \return \c -1 if the output buffer is too small or the input string
Ronald Cronab500cb2020-07-01 17:09:10 +0200208 * is not a valid hexadecimal representation.
Ronald Crona0c25392020-06-18 10:10:46 +0200209 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100210int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax,
211 const char *ibuf, size_t *len);
Ronald Crona0c25392020-06-18 10:10:46 +0200212
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100213void mbedtls_test_hexify(unsigned char *obuf,
214 const unsigned char *ibuf,
215 int len);
Ronald Cronf40529d2020-06-09 16:27:37 +0200216
217/**
218 * Allocate and zeroize a buffer.
219 *
220 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
221 *
222 * For convenience, dies if allocation fails.
223 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100224unsigned char *mbedtls_test_zero_alloc(size_t len);
Ronald Cronf40529d2020-06-09 16:27:37 +0200225
226/**
227 * Allocate and fill a buffer from hex data.
228 *
229 * The buffer is sized exactly as needed. This allows to detect buffer
230 * overruns (including overreads) when running the test suite under valgrind.
231 *
232 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
233 *
234 * For convenience, dies if allocation fails.
235 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100236unsigned char *mbedtls_test_unhexify_alloc(const char *ibuf, size_t *olen);
Ronald Cronf40529d2020-06-09 16:27:37 +0200237
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100238int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b,
239 uint32_t a_len, uint32_t b_len);
Ronald Cronf40529d2020-06-09 16:27:37 +0200240
Ronald Crona1236142020-07-01 16:01:21 +0200241#if defined(MBEDTLS_CHECK_PARAMS)
242
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100243typedef struct {
Ronald Crona1236142020-07-01 16:01:21 +0200244 const char *failure_condition;
245 const char *file;
246 int line;
247}
248mbedtls_test_param_failed_location_record_t;
249
250/**
251 * \brief Get the location record of the last call to
252 * mbedtls_test_param_failed().
253 *
254 * \note The call expectation is set up and active until the next call to
255 * mbedtls_test_param_failed_check_expected_call() or
256 * mbedtls_param_failed() that cancels it.
257 */
258void mbedtls_test_param_failed_get_location_record(
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100259 mbedtls_test_param_failed_location_record_t *location_record);
Ronald Crona1236142020-07-01 16:01:21 +0200260
261/**
262 * \brief State that a call to mbedtls_param_failed() is expected.
263 *
264 * \note The call expectation is set up and active until the next call to
265 * mbedtls_test_param_failed_check_expected_call() or
266 * mbedtls_param_failed that cancel it.
267 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100268void mbedtls_test_param_failed_expect_call(void);
Ronald Crona1236142020-07-01 16:01:21 +0200269
270/**
271 * \brief Check whether mbedtls_param_failed() has been called as expected.
272 *
273 * \note Check whether mbedtls_param_failed() has been called between the
274 * last call to mbedtls_test_param_failed_expect_call() and the call
275 * to this function.
276 *
277 * \return \c 0 Since the last call to mbedtls_param_failed_expect_call(),
278 * mbedtls_param_failed() has been called.
279 * \c -1 Otherwise.
280 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100281int mbedtls_test_param_failed_check_expected_call(void);
Ronald Crona1236142020-07-01 16:01:21 +0200282
283/**
Ronald Cronbf4f4082020-09-25 10:45:06 +0200284 * \brief Get the address of the object of type jmp_buf holding the execution
Ronald Crona1236142020-07-01 16:01:21 +0200285 * state information used by mbedtls_param_failed() to do a long jump.
286 *
287 * \note If a call to mbedtls_param_failed() is not expected in the sense
288 * that there is no call to mbedtls_test_param_failed_expect_call()
289 * preceding it, then mbedtls_param_failed() will try to restore the
290 * execution to the state stored in the jmp_buf object whose address
291 * is returned by the present function.
292 *
Ronald Cronbf4f4082020-09-25 10:45:06 +0200293 * \note This function is intended to provide the parameter of the
294 * setjmp() function to set-up where mbedtls_param_failed() should
295 * long-jump if it has to. It is foreseen to be used as:
296 *
297 * setjmp( mbedtls_test_param_failed_get_state_buf() ).
298 *
299 * \note The type of the returned value is not jmp_buf as jmp_buf is an
300 * an array type (C specification) and a function cannot return an
301 * array type.
302 *
303 * \note The type of the returned value is not jmp_buf* as then the return
304 * value couldn't be used by setjmp(), as its parameter's type is
305 * jmp_buf.
Ronald Crona1236142020-07-01 16:01:21 +0200306 *
307 * \return Address of the object of type jmp_buf holding the execution state
308 * information used by mbedtls_param_failed() to do a long jump.
309 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100310void *mbedtls_test_param_failed_get_state_buf(void);
Ronald Crona1236142020-07-01 16:01:21 +0200311
312/**
313 * \brief Reset the execution state used by mbedtls_param_failed() to do a
314 * long jump.
315 *
316 * \note If a call to mbedtls_param_failed() is not expected in the sense
317 * that there is no call to mbedtls_test_param_failed_expect_call()
318 * preceding it, then mbedtls_param_failed() will try to restore the
319 * execution state that this function reset.
320 *
321 * \note It is recommended to reset the execution state when the state
322 * is not relevant anymore. That way an unexpected call to
323 * mbedtls_param_failed() will not trigger a long jump with
324 * undefined behavior but rather a long jump that will rather fault.
325 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100326void mbedtls_test_param_failed_reset_state(void);
Ronald Crona1236142020-07-01 16:01:21 +0200327#endif /* MBEDTLS_CHECK_PARAMS */
328
Gilles Peskine1dc19ff2021-02-08 20:59:39 +0100329#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
Gilles Peskine1af872d2021-01-20 20:02:01 +0100330#include "test/fake_external_rng_for_test.h"
331#endif
332
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100333#if defined(MBEDTLS_TEST_MUTEX_USAGE)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100334/** Permanently activate the mutex usage verification framework. See
335 * threading_helpers.c for information. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100336void mbedtls_test_mutex_usage_init(void);
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100337
338/** Call this function after executing a test case to check for mutex usage
339 * errors. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100340void mbedtls_test_mutex_usage_check(void);
Gilles Peskine1061ec62021-01-29 21:17:11 +0100341#endif /* MBEDTLS_TEST_MUTEX_USAGE */
342
Chris Jones96ae73b2021-01-08 17:04:59 +0000343#if defined(MBEDTLS_TEST_HOOKS)
344/**
Chris Jones3f613c12021-03-31 09:34:22 +0100345 * \brief Check that only a pure high-level error code is being combined with
346 * a pure low-level error code as otherwise the resultant error code
Chris Jones5e8805a2021-01-12 15:21:57 +0000347 * would be corrupted.
Chris Jones3f613c12021-03-31 09:34:22 +0100348 *
349 * \note Both high-level and low-level error codes cannot be greater than
350 * zero however can be zero. If one error code is zero then the
351 * other error code is returned even if both codes are zero.
352 *
353 * \note If the check fails, fail the test currently being run.
Chris Jones96ae73b2021-01-08 17:04:59 +0000354 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100355void mbedtls_test_err_add_check(int high, int low,
356 const char *file, int line);
Chris Jones96ae73b2021-01-08 17:04:59 +0000357#endif
358
Gilles Peskinedb479712021-06-11 14:13:53 +0200359#if defined(MBEDTLS_BIGNUM_C)
Werner Lewis24b60782022-07-07 15:08:17 +0100360/** Read an MPI from a hexadecimal string.
Gilles Peskinedb479712021-06-11 14:13:53 +0200361 *
Gilles Peskine53a72062022-11-09 21:08:44 +0100362 * Like mbedtls_mpi_read_string(), but with tighter guarantees around
363 * edge cases.
Gilles Peskinedb479712021-06-11 14:13:53 +0200364 *
Gilles Peskine53a72062022-11-09 21:08:44 +0100365 * - This function guarantees that if \p s begins with '-' then the sign
366 * bit of the result will be negative, even if the value is 0.
367 * When this function encounters such a "negative 0", it
Gilles Peskined64123a2022-11-11 15:59:51 +0100368 * increments #mbedtls_test_case_uses_negative_0.
Gilles Peskine53a72062022-11-09 21:08:44 +0100369 * - The size of the result is exactly the minimum number of limbs needed
370 * to fit the digits in the input. In particular, this function constructs
371 * a bignum with 0 limbs for an empty string, and a bignum with leading 0
372 * limbs if the string has sufficiently many leading 0 digits.
373 * This is important so that the "0 (null)" and "0 (1 limb)" and
374 * "leading zeros" test cases do what they claim.
Gilles Peskinedb479712021-06-11 14:13:53 +0200375 *
376 * \param[out] X The MPI object to populate. It must be initialized.
Werner Lewis24b60782022-07-07 15:08:17 +0100377 * \param[in] s The null-terminated hexadecimal string to read from.
Gilles Peskinedb479712021-06-11 14:13:53 +0200378 *
379 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise.
380 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100381int mbedtls_test_read_mpi(mbedtls_mpi *X, const char *s);
Gilles Peskine53a72062022-11-09 21:08:44 +0100382
383/** Nonzero if the current test case had an input parsed with
384 * mbedtls_test_read_mpi() that is a negative 0 (`"-"`, `"-0"`, `"-00"`, etc.,
385 * constructing a result with the sign bit set to -1 and the value being
386 * all-limbs-0, which is not a valid representation in #mbedtls_mpi but is
387 * tested for robustness).
388 */
389extern unsigned mbedtls_test_case_uses_negative_0;
Gilles Peskinedb479712021-06-11 14:13:53 +0200390#endif /* MBEDTLS_BIGNUM_C */
391
Ronald Cronb6d6d4c2020-06-03 10:11:18 +0200392#endif /* TEST_HELPERS_H */