blob: c3a844b600a0663ac1c483fee1aa5c73b808c576 [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
Chris Jones9634bb12021-01-20 15:56:42 +000057typedef enum
58{
Chris Jonese60e2ae2021-01-20 17:51:47 +000059 MBEDTLS_TEST_RESULT_SUCCESS = 0,
60 MBEDTLS_TEST_RESULT_FAILED,
61 MBEDTLS_TEST_RESULT_SKIPPED
62} mbedtls_test_result_t;
Chris Jones9634bb12021-01-20 15:56:42 +000063
64typedef struct
65{
Chris Jonese60e2ae2021-01-20 17:51:47 +000066 mbedtls_test_result_t result;
Chris Jones9634bb12021-01-20 15:56:42 +000067 const char *test;
68 const char *filename;
69 int line_no;
70 unsigned long step;
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
Ronald Crone9c09f12020-06-08 16:44:58 +020078int 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 */
Chris Jones9634bb12021-01-20 15:56:42 +000097void 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 */
Chris Jonesa5ab7652021-02-02 16:20:45 +0000110void 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 */
122void mbedtls_test_set_step( unsigned long step );
123
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 */
Chris Jonesa5ab7652021-02-02 16:20:45 +0000127void mbedtls_test_info_reset( void );
Chris Jones9634bb12021-01-20 15:56:42 +0000128
Ronald Crona0c25392020-06-18 10:10:46 +0200129/**
Ronald Cronab500cb2020-07-01 17:09:10 +0200130 * \brief This function decodes the hexadecimal representation of
131 * data.
Ronald Crona0c25392020-06-18 10:10:46 +0200132 *
133 * \note The output buffer can be the same as the input buffer. For
134 * any other overlapping of the input and output buffers, the
135 * behavior is undefined.
136 *
137 * \param obuf Output buffer.
138 * \param obufmax Size in number of bytes of \p obuf.
139 * \param ibuf Input buffer.
140 * \param len The number of unsigned char written in \p obuf. This must
141 * not be \c NULL.
142 *
143 * \return \c 0 on success.
144 * \return \c -1 if the output buffer is too small or the input string
Ronald Cronab500cb2020-07-01 17:09:10 +0200145 * is not a valid hexadecimal representation.
Ronald Crona0c25392020-06-18 10:10:46 +0200146 */
147int mbedtls_test_unhexify( unsigned char *obuf, size_t obufmax,
148 const char *ibuf, size_t *len );
149
Ronald Cron72d628f2020-06-08 17:05:57 +0200150void mbedtls_test_hexify( unsigned char *obuf,
151 const unsigned char *ibuf,
152 int len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200153
154/**
155 * Allocate and zeroize a buffer.
156 *
157 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
158 *
159 * For convenience, dies if allocation fails.
160 */
Ronald Cron690f3eb2020-06-10 10:42:18 +0200161unsigned char *mbedtls_test_zero_alloc( size_t len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200162
163/**
164 * Allocate and fill a buffer from hex data.
165 *
166 * The buffer is sized exactly as needed. This allows to detect buffer
167 * overruns (including overreads) when running the test suite under valgrind.
168 *
169 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
170 *
171 * For convenience, dies if allocation fails.
172 */
Ronald Crona256c702020-06-10 10:53:11 +0200173unsigned char *mbedtls_test_unhexify_alloc( const char *ibuf, size_t *olen );
Ronald Cronf40529d2020-06-09 16:27:37 +0200174
Ronald Cronde70b162020-06-10 11:03:08 +0200175int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b,
176 uint32_t a_len, uint32_t b_len );
Ronald Cronf40529d2020-06-09 16:27:37 +0200177
Ronald Crona1236142020-07-01 16:01:21 +0200178#if defined(MBEDTLS_CHECK_PARAMS)
179
180typedef struct
181{
182 const char *failure_condition;
183 const char *file;
184 int line;
185}
186mbedtls_test_param_failed_location_record_t;
187
188/**
189 * \brief Get the location record of the last call to
190 * mbedtls_test_param_failed().
191 *
192 * \note The call expectation is set up and active until the next call to
193 * mbedtls_test_param_failed_check_expected_call() or
194 * mbedtls_param_failed() that cancels it.
195 */
196void mbedtls_test_param_failed_get_location_record(
197 mbedtls_test_param_failed_location_record_t *location_record );
198
199/**
200 * \brief State that a call to mbedtls_param_failed() is expected.
201 *
202 * \note The call expectation is set up and active until the next call to
203 * mbedtls_test_param_failed_check_expected_call() or
204 * mbedtls_param_failed that cancel it.
205 */
206void mbedtls_test_param_failed_expect_call( void );
207
208/**
209 * \brief Check whether mbedtls_param_failed() has been called as expected.
210 *
211 * \note Check whether mbedtls_param_failed() has been called between the
212 * last call to mbedtls_test_param_failed_expect_call() and the call
213 * to this function.
214 *
215 * \return \c 0 Since the last call to mbedtls_param_failed_expect_call(),
216 * mbedtls_param_failed() has been called.
217 * \c -1 Otherwise.
218 */
219int mbedtls_test_param_failed_check_expected_call( void );
220
221/**
Ronald Cronbf4f4082020-09-25 10:45:06 +0200222 * \brief Get the address of the object of type jmp_buf holding the execution
Ronald Crona1236142020-07-01 16:01:21 +0200223 * state information used by mbedtls_param_failed() to do a long jump.
224 *
225 * \note If a call to mbedtls_param_failed() is not expected in the sense
226 * that there is no call to mbedtls_test_param_failed_expect_call()
227 * preceding it, then mbedtls_param_failed() will try to restore the
228 * execution to the state stored in the jmp_buf object whose address
229 * is returned by the present function.
230 *
Ronald Cronbf4f4082020-09-25 10:45:06 +0200231 * \note This function is intended to provide the parameter of the
232 * setjmp() function to set-up where mbedtls_param_failed() should
233 * long-jump if it has to. It is foreseen to be used as:
234 *
235 * setjmp( mbedtls_test_param_failed_get_state_buf() ).
236 *
237 * \note The type of the returned value is not jmp_buf as jmp_buf is an
238 * an array type (C specification) and a function cannot return an
239 * array type.
240 *
241 * \note The type of the returned value is not jmp_buf* as then the return
242 * value couldn't be used by setjmp(), as its parameter's type is
243 * jmp_buf.
Ronald Crona1236142020-07-01 16:01:21 +0200244 *
245 * \return Address of the object of type jmp_buf holding the execution state
246 * information used by mbedtls_param_failed() to do a long jump.
247 */
248void* mbedtls_test_param_failed_get_state_buf( void );
249
250/**
251 * \brief Reset the execution state used by mbedtls_param_failed() to do a
252 * long jump.
253 *
254 * \note If a call to mbedtls_param_failed() is not expected in the sense
255 * that there is no call to mbedtls_test_param_failed_expect_call()
256 * preceding it, then mbedtls_param_failed() will try to restore the
257 * execution state that this function reset.
258 *
259 * \note It is recommended to reset the execution state when the state
260 * is not relevant anymore. That way an unexpected call to
261 * mbedtls_param_failed() will not trigger a long jump with
262 * undefined behavior but rather a long jump that will rather fault.
263 */
264void mbedtls_test_param_failed_reset_state( void );
265#endif /* MBEDTLS_CHECK_PARAMS */
266
Gilles Peskine1dc19ff2021-02-08 20:59:39 +0100267#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
Gilles Peskine1af872d2021-01-20 20:02:01 +0100268#include "test/fake_external_rng_for_test.h"
269#endif
270
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100271#if defined(MBEDTLS_TEST_MUTEX_USAGE)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100272/** Permanently activate the mutex usage verification framework. See
273 * threading_helpers.c for information. */
274void mbedtls_test_mutex_usage_init( void );
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100275
276/** Call this function after executing a test case to check for mutex usage
277 * errors. */
278void mbedtls_test_mutex_usage_check( void );
Gilles Peskine1061ec62021-01-29 21:17:11 +0100279#endif /* MBEDTLS_TEST_MUTEX_USAGE */
280
Ronald Cronb6d6d4c2020-06-03 10:11:18 +0200281#endif /* TEST_HELPERS_H */