blob: 757a43be4a28b862f725d75387f44886eec6f561 [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
Ronald Cronb6d6d4c2020-06-03 10:11:18 +020010 * 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 Cronb6d6d4c2020-06-03 10:11:18 +020023 */
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 Peskine2a4c5982021-01-29 21:18:09 +010034#if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \
35 defined(MBEDTLS_TEST_HOOKS)
36#define MBEDTLS_TEST_MUTEX_USAGE
37#endif
38
Ronald Cronf40529d2020-06-09 16:27:37 +020039#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 Peskinedb479712021-06-11 14:13:53 +020057#if defined(MBEDTLS_BIGNUM_C)
58#include "mbedtls/bignum.h"
59#endif
60
Gilles Peskine34cb4622022-09-20 21:37:56 +020061/** The type of test case arguments that contain binary data. */
62typedef struct data_tag
63{
64 uint8_t * x;
65 uint32_t len;
66} data_t;
67
Chris Jones9634bb12021-01-20 15:56:42 +000068typedef enum
69{
Chris Jonese60e2ae2021-01-20 17:51:47 +000070 MBEDTLS_TEST_RESULT_SUCCESS = 0,
71 MBEDTLS_TEST_RESULT_FAILED,
72 MBEDTLS_TEST_RESULT_SKIPPED
73} mbedtls_test_result_t;
Chris Jones9634bb12021-01-20 15:56:42 +000074
75typedef struct
76{
Chris Jonese60e2ae2021-01-20 17:51:47 +000077 mbedtls_test_result_t result;
Chris Jones9634bb12021-01-20 15:56:42 +000078 const char *test;
79 const char *filename;
80 int line_no;
81 unsigned long step;
Gilles Peskineb4366492021-04-29 20:28:54 +020082 char line1[76];
83 char line2[76];
Gilles Peskine2a4c5982021-01-29 21:18:09 +010084#if defined(MBEDTLS_TEST_MUTEX_USAGE)
85 const char *mutex_usage_error;
86#endif
Chris Jones9634bb12021-01-20 15:56:42 +000087}
Chris Jonese60e2ae2021-01-20 17:51:47 +000088mbedtls_test_info_t;
89extern mbedtls_test_info_t mbedtls_test_info;
Chris Jones9634bb12021-01-20 15:56:42 +000090
Ronald Crone9c09f12020-06-08 16:44:58 +020091int mbedtls_test_platform_setup( void );
92void mbedtls_test_platform_teardown( void );
Ronald Cronf40529d2020-06-09 16:27:37 +020093
Ronald Crona0c25392020-06-18 10:10:46 +020094/**
Chris Jones39ddb0a2021-02-03 16:15:00 +000095 * \brief Record the current test case as a failure.
Chris Jones567e0ad2021-02-03 12:07:01 +000096 *
Chris Jones39ddb0a2021-02-03 16:15:00 +000097 * This function can be called directly however it is usually
98 * called via macros such as TEST_ASSERT, TEST_EQUAL,
99 * PSA_ASSERT, etc...
100 *
101 * \note If the test case was already marked as failed, calling
102 * `mbedtls_test_fail( )` again will not overwrite any
103 * previous information about the failure.
104 *
105 * \param test Description of the failure or assertion that failed. This
106 * MUST be a string literal.
Chris Jones567e0ad2021-02-03 12:07:01 +0000107 * \param line_no Line number where the failure originated.
108 * \param filename Filename where the failure originated.
109 */
Chris Jones9634bb12021-01-20 15:56:42 +0000110void mbedtls_test_fail( const char *test, int line_no, const char* filename );
Chris Jones567e0ad2021-02-03 12:07:01 +0000111
112/**
Chris Jones39ddb0a2021-02-03 16:15:00 +0000113 * \brief Record the current test case as skipped.
Chris Jones567e0ad2021-02-03 12:07:01 +0000114 *
Chris Jones39ddb0a2021-02-03 16:15:00 +0000115 * This function can be called directly however it is usually
116 * called via the TEST_ASSUME macro.
117 *
118 * \param test Description of the assumption that caused the test case to
119 * be skipped. This MUST be a string literal.
120 * \param line_no Line number where the test case was skipped.
121 * \param filename Filename where the test case was skipped.
Chris Jones567e0ad2021-02-03 12:07:01 +0000122 */
Chris Jonesa5ab7652021-02-02 16:20:45 +0000123void mbedtls_test_skip( const char *test, int line_no, const char* filename );
Chris Jones9634bb12021-01-20 15:56:42 +0000124
Chris Jones567e0ad2021-02-03 12:07:01 +0000125/**
126 * \brief Set the test step number for failure reports.
Chris Jones9634bb12021-01-20 15:56:42 +0000127 *
Chris Jones39ddb0a2021-02-03 16:15:00 +0000128 * Call this function to display "step NNN" in addition to the
Chris Jones567e0ad2021-02-03 12:07:01 +0000129 * line number and file name if a test fails. Typically the "step
130 * number" is the index of a for loop but it can be whatever you
131 * want.
Chris Jones9634bb12021-01-20 15:56:42 +0000132 *
133 * \param step The step number to report.
134 */
135void mbedtls_test_set_step( unsigned long step );
136
Chris Jones567e0ad2021-02-03 12:07:01 +0000137/**
138 * \brief Reset mbedtls_test_info to a ready/starting state.
Chris Jones567e0ad2021-02-03 12:07:01 +0000139 */
Chris Jonesa5ab7652021-02-02 16:20:45 +0000140void mbedtls_test_info_reset( void );
Chris Jones9634bb12021-01-20 15:56:42 +0000141
Ronald Crona0c25392020-06-18 10:10:46 +0200142/**
Gilles Peskineb4366492021-04-29 20:28:54 +0200143 * \brief Record the current test case as a failure if two integers
144 * have a different value.
145 *
146 * This function is usually called via the macro
147 * #TEST_EQUAL.
148 *
149 * \param test Description of the failure or assertion that failed. This
150 * MUST be a string literal. This normally has the form
151 * "EXPR1 == EXPR2" where EXPR1 has the value \p value1
152 * and EXPR2 has the value \p value2.
153 * \param line_no Line number where the failure originated.
154 * \param filename Filename where the failure originated.
155 * \param value1 The first value to compare.
156 * \param value2 The second value to compare.
157 *
158 * \return \c 1 if the values are equal, otherwise \c 0.
159 */
160int mbedtls_test_equal( const char *test, int line_no, const char* filename,
161 unsigned long long value1, unsigned long long value2 );
162
163/**
Gilles Peskine063700d2022-04-13 23:59:52 +0200164 * \brief Record the current test case as a failure based
165 * on comparing two unsigned integers.
166 *
167 * This function is usually called via the macro
168 * #TEST_LE_U.
169 *
170 * \param test Description of the failure or assertion that failed. This
171 * MUST be a string literal. This normally has the form
172 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
173 * and EXPR2 has the value \p value2.
174 * \param line_no Line number where the failure originated.
175 * \param filename Filename where the failure originated.
176 * \param value1 The first value to compare.
177 * \param value2 The second value to compare.
178 *
179 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
180 */
181int mbedtls_test_le_u( const char *test, int line_no, const char* filename,
182 unsigned long long value1, unsigned long long value2 );
183
184/**
185 * \brief Record the current test case as a failure based
186 * on comparing two signed integers.
187 *
188 * This function is usually called via the macro
189 * #TEST_LE_S.
190 *
191 * \param test Description of the failure or assertion that failed. This
192 * MUST be a string literal. This normally has the form
193 * "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
194 * and EXPR2 has the value \p value2.
195 * \param line_no Line number where the failure originated.
196 * \param filename Filename where the failure originated.
197 * \param value1 The first value to compare.
198 * \param value2 The second value to compare.
199 *
200 * \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
201 */
202int mbedtls_test_le_s( const char *test, int line_no, const char* filename,
203 long long value1, long long value2 );
204
205/**
Ronald Cronab500cb2020-07-01 17:09:10 +0200206 * \brief This function decodes the hexadecimal representation of
207 * data.
Ronald Crona0c25392020-06-18 10:10:46 +0200208 *
209 * \note The output buffer can be the same as the input buffer. For
210 * any other overlapping of the input and output buffers, the
211 * behavior is undefined.
212 *
213 * \param obuf Output buffer.
214 * \param obufmax Size in number of bytes of \p obuf.
215 * \param ibuf Input buffer.
216 * \param len The number of unsigned char written in \p obuf. This must
217 * not be \c NULL.
218 *
219 * \return \c 0 on success.
220 * \return \c -1 if the output buffer is too small or the input string
Ronald Cronab500cb2020-07-01 17:09:10 +0200221 * is not a valid hexadecimal representation.
Ronald Crona0c25392020-06-18 10:10:46 +0200222 */
223int mbedtls_test_unhexify( unsigned char *obuf, size_t obufmax,
224 const char *ibuf, size_t *len );
225
Ronald Cron72d628f2020-06-08 17:05:57 +0200226void mbedtls_test_hexify( unsigned char *obuf,
227 const unsigned char *ibuf,
228 int len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200229
230/**
231 * Allocate and zeroize a buffer.
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 */
Ronald Cron690f3eb2020-06-10 10:42:18 +0200237unsigned char *mbedtls_test_zero_alloc( size_t len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200238
239/**
240 * Allocate and fill a buffer from hex data.
241 *
242 * The buffer is sized exactly as needed. This allows to detect buffer
243 * overruns (including overreads) when running the test suite under valgrind.
244 *
245 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
246 *
247 * For convenience, dies if allocation fails.
248 */
Ronald Crona256c702020-06-10 10:53:11 +0200249unsigned char *mbedtls_test_unhexify_alloc( const char *ibuf, size_t *olen );
Ronald Cronf40529d2020-06-09 16:27:37 +0200250
Ronald Cronde70b162020-06-10 11:03:08 +0200251int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b,
252 uint32_t a_len, uint32_t b_len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200253
Ronald Crona1236142020-07-01 16:01:21 +0200254#if defined(MBEDTLS_CHECK_PARAMS)
255
256typedef struct
257{
258 const char *failure_condition;
259 const char *file;
260 int line;
261}
262mbedtls_test_param_failed_location_record_t;
263
264/**
265 * \brief Get the location record of the last call to
266 * mbedtls_test_param_failed().
267 *
268 * \note The call expectation is set up and active until the next call to
269 * mbedtls_test_param_failed_check_expected_call() or
270 * mbedtls_param_failed() that cancels it.
271 */
272void mbedtls_test_param_failed_get_location_record(
273 mbedtls_test_param_failed_location_record_t *location_record );
274
275/**
276 * \brief State that a call to mbedtls_param_failed() is expected.
277 *
278 * \note The call expectation is set up and active until the next call to
279 * mbedtls_test_param_failed_check_expected_call() or
280 * mbedtls_param_failed that cancel it.
281 */
282void mbedtls_test_param_failed_expect_call( void );
283
284/**
285 * \brief Check whether mbedtls_param_failed() has been called as expected.
286 *
287 * \note Check whether mbedtls_param_failed() has been called between the
288 * last call to mbedtls_test_param_failed_expect_call() and the call
289 * to this function.
290 *
291 * \return \c 0 Since the last call to mbedtls_param_failed_expect_call(),
292 * mbedtls_param_failed() has been called.
293 * \c -1 Otherwise.
294 */
295int mbedtls_test_param_failed_check_expected_call( void );
296
297/**
Ronald Cronbf4f4082020-09-25 10:45:06 +0200298 * \brief Get the address of the object of type jmp_buf holding the execution
Ronald Crona1236142020-07-01 16:01:21 +0200299 * state information used by mbedtls_param_failed() to do a long jump.
300 *
301 * \note If a call to mbedtls_param_failed() is not expected in the sense
302 * that there is no call to mbedtls_test_param_failed_expect_call()
303 * preceding it, then mbedtls_param_failed() will try to restore the
304 * execution to the state stored in the jmp_buf object whose address
305 * is returned by the present function.
306 *
Ronald Cronbf4f4082020-09-25 10:45:06 +0200307 * \note This function is intended to provide the parameter of the
308 * setjmp() function to set-up where mbedtls_param_failed() should
309 * long-jump if it has to. It is foreseen to be used as:
310 *
311 * setjmp( mbedtls_test_param_failed_get_state_buf() ).
312 *
313 * \note The type of the returned value is not jmp_buf as jmp_buf is an
314 * an array type (C specification) and a function cannot return an
315 * array type.
316 *
317 * \note The type of the returned value is not jmp_buf* as then the return
318 * value couldn't be used by setjmp(), as its parameter's type is
319 * jmp_buf.
Ronald Crona1236142020-07-01 16:01:21 +0200320 *
321 * \return Address of the object of type jmp_buf holding the execution state
322 * information used by mbedtls_param_failed() to do a long jump.
323 */
324void* mbedtls_test_param_failed_get_state_buf( void );
325
326/**
327 * \brief Reset the execution state used by mbedtls_param_failed() to do a
328 * long jump.
329 *
330 * \note If a call to mbedtls_param_failed() is not expected in the sense
331 * that there is no call to mbedtls_test_param_failed_expect_call()
332 * preceding it, then mbedtls_param_failed() will try to restore the
333 * execution state that this function reset.
334 *
335 * \note It is recommended to reset the execution state when the state
336 * is not relevant anymore. That way an unexpected call to
337 * mbedtls_param_failed() will not trigger a long jump with
338 * undefined behavior but rather a long jump that will rather fault.
339 */
340void mbedtls_test_param_failed_reset_state( void );
341#endif /* MBEDTLS_CHECK_PARAMS */
342
Gilles Peskine1dc19ff2021-02-08 20:59:39 +0100343#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
Gilles Peskine1af872d2021-01-20 20:02:01 +0100344#include "test/fake_external_rng_for_test.h"
345#endif
346
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100347#if defined(MBEDTLS_TEST_MUTEX_USAGE)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100348/** Permanently activate the mutex usage verification framework. See
349 * threading_helpers.c for information. */
350void mbedtls_test_mutex_usage_init( void );
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100351
352/** Call this function after executing a test case to check for mutex usage
353 * errors. */
354void mbedtls_test_mutex_usage_check( void );
Gilles Peskine1061ec62021-01-29 21:17:11 +0100355#endif /* MBEDTLS_TEST_MUTEX_USAGE */
356
Chris Jones96ae73b2021-01-08 17:04:59 +0000357#if defined(MBEDTLS_TEST_HOOKS)
358/**
Chris Jones3f613c12021-03-31 09:34:22 +0100359 * \brief Check that only a pure high-level error code is being combined with
360 * a pure low-level error code as otherwise the resultant error code
Chris Jones5e8805a2021-01-12 15:21:57 +0000361 * would be corrupted.
Chris Jones3f613c12021-03-31 09:34:22 +0100362 *
363 * \note Both high-level and low-level error codes cannot be greater than
364 * zero however can be zero. If one error code is zero then the
365 * other error code is returned even if both codes are zero.
366 *
367 * \note If the check fails, fail the test currently being run.
Chris Jones96ae73b2021-01-08 17:04:59 +0000368 */
369void mbedtls_test_err_add_check( int high, int low,
370 const char *file, int line);
371#endif
372
Gilles Peskinedb479712021-06-11 14:13:53 +0200373#if defined(MBEDTLS_BIGNUM_C)
Werner Lewis24b60782022-07-07 15:08:17 +0100374/** Read an MPI from a hexadecimal string.
Gilles Peskinedb479712021-06-11 14:13:53 +0200375 *
376 * Like mbedtls_mpi_read_string(), but size the resulting bignum based
377 * on the number of digits in the string. In particular, construct a
378 * bignum with 0 limbs for an empty string, and a bignum with leading 0
379 * limbs if the string has sufficiently many leading 0 digits.
380 *
381 * This is important so that the "0 (null)" and "0 (1 limb)" and
382 * "leading zeros" test cases do what they claim.
383 *
384 * \param[out] X The MPI object to populate. It must be initialized.
Werner Lewis24b60782022-07-07 15:08:17 +0100385 * \param[in] s The null-terminated hexadecimal string to read from.
Gilles Peskinedb479712021-06-11 14:13:53 +0200386 *
387 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise.
388 */
Werner Lewis24b60782022-07-07 15:08:17 +0100389int mbedtls_test_read_mpi( mbedtls_mpi *X, const char *s );
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 */