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 OR GPL-2.0-or-later
11 */
12
13#ifndef TEST_HELPERS_H
14#define TEST_HELPERS_H
15
16/* Most fields of publicly available structs are private and are wrapped with
17 * MBEDTLS_PRIVATE macro. This define allows tests to access the private fields
18 * directly (without using the MBEDTLS_PRIVATE wrapper). */
19#define MBEDTLS_ALLOW_PRIVATE_ACCESS
20
21#include "mbedtls/build_info.h"
22
23#if defined(__SANITIZE_ADDRESS__) /* gcc -fsanitize=address */
24#  define MBEDTLS_TEST_HAVE_ASAN
25#endif
26#if defined(__SANITIZE_THREAD__) /* gcc -fsanitize-thread */
27#  define MBEDTLS_TEST_HAVE_TSAN
28#endif
29
30#if defined(__has_feature)
31#  if __has_feature(address_sanitizer) /* clang -fsanitize=address */
32#    define MBEDTLS_TEST_HAVE_ASAN
33#  endif
34#  if __has_feature(memory_sanitizer) /* clang -fsanitize=memory */
35#    define MBEDTLS_TEST_HAVE_MSAN
36#  endif
37#  if __has_feature(thread_sanitizer) /* clang -fsanitize=thread */
38#    define MBEDTLS_TEST_HAVE_TSAN
39#  endif
40#endif
41
42#include "test/threading_helpers.h"
43
44#if defined(MBEDTLS_TEST_MUTEX_USAGE)
45#include "mbedtls/threading.h"
46#endif
47
48#include "mbedtls/platform.h"
49
50#include <stddef.h>
51#include <stdint.h>
52
53#if defined(MBEDTLS_BIGNUM_C)
54#include "mbedtls/bignum.h"
55#endif
56
57/** The type of test case arguments that contain binary data. */
58typedef struct data_tag {
59    uint8_t *x;
60    uint32_t    len;
61} data_t;
62
63typedef enum {
64    MBEDTLS_TEST_RESULT_SUCCESS = 0,
65    MBEDTLS_TEST_RESULT_FAILED,
66    MBEDTLS_TEST_RESULT_SKIPPED
67} mbedtls_test_result_t;
68
69#define MBEDTLS_TEST_LINE_LENGTH 76
70
71typedef struct {
72    mbedtls_test_result_t result;
73    const char *test;
74    const char *filename;
75    int line_no;
76    unsigned long step;
77    char line1[MBEDTLS_TEST_LINE_LENGTH];
78    char line2[MBEDTLS_TEST_LINE_LENGTH];
79#if defined(MBEDTLS_TEST_MUTEX_USAGE)
80    const char *mutex_usage_error;
81#endif
82#if defined(MBEDTLS_BIGNUM_C)
83    unsigned case_uses_negative_0;
84#endif
85}
86mbedtls_test_info_t;
87
88/**
89 * \brief           Get the current test result status
90 *
91 * \return          The current test result status
92 */
93mbedtls_test_result_t mbedtls_test_get_result(void);
94
95/**
96 * \brief           Get the current test name/description
97 *
98 * \return          The current test name/description
99 */
100const char *mbedtls_test_get_test(void);
101
102/**
103 * \brief           Get the current test filename
104 *
105 * \return          The current test filename
106 */
107const char *mbedtls_get_test_filename(void);
108
109/**
110 * \brief           Get the current test file line number (for failure / skip)
111 *
112 * \return          The current test file line number (for failure / skip)
113 */
114int mbedtls_test_get_line_no(void);
115
116/**
117 * \brief           Increment the current test step.
118 *
119 * \note            It is not recommended for multiple threads to call this
120 *                  function concurrently - whilst it is entirely thread safe,
121 *                  the order of calls to this function can obviously not be
122 *                  ensured, so unexpected results may occur.
123 */
124void mbedtls_test_increment_step(void);
125
126/**
127 * \brief           Get the current test step
128 *
129 * \return          The current test step
130 */
131unsigned long mbedtls_test_get_step(void);
132
133/**
134 * \brief           Get the current test line buffer 1
135 *
136 * \param line      Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH,
137 *                  which will have line buffer 1 copied to it.
138 */
139void mbedtls_test_get_line1(char *line);
140
141/**
142 * \brief           Get the current test line buffer 2
143 *
144 * \param line      Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH,
145 *                  which will have line buffer 1 copied to it.
146 */
147void mbedtls_test_get_line2(char *line);
148
149#if defined(MBEDTLS_TEST_MUTEX_USAGE)
150/**
151 * \brief           Get the current mutex usage error message
152 *
153 * \return          The current mutex error message (may be NULL if no error)
154 */
155const char *mbedtls_test_get_mutex_usage_error(void);
156
157/**
158 * \brief           Set the current mutex usage error message
159 *
160 * \note            This will only set the mutex error message if one has not
161 *                  already been set, or if we are clearing the message (msg is
162 *                  NULL)
163 *
164 * \param msg       Error message to set (can be NULL to clear)
165 */
166void mbedtls_test_set_mutex_usage_error(const char *msg);
167#endif
168
169#if defined(MBEDTLS_BIGNUM_C)
170
171/**
172 * \brief           Get whether the current test is a bignum test that uses
173 *                  negative zero.
174 *
175 * \return          non zero if the current test uses bignum negative zero.
176 */
177unsigned mbedtls_test_get_case_uses_negative_0(void);
178
179/**
180 * \brief           Indicate that the current test uses bignum negative zero.
181 *
182 * \note            This function is called if the current test case had an
183 *                  input parsed with mbedtls_test_read_mpi() that is a negative
184 *                  0 (`"-"`, `"-0"`, `"-00"`, etc., constructing a result with
185 *                  the sign bit set to -1 and the value being all-limbs-0,
186 *                  which is not a valid representation in #mbedtls_mpi but is
187 *                  tested for robustness). *
188 */
189void  mbedtls_test_increment_case_uses_negative_0(void);
190#endif
191
192int mbedtls_test_platform_setup(void);
193void mbedtls_test_platform_teardown(void);
194
195/**
196 * \brief           Record the current test case as a failure.
197 *
198 *                  This function can be called directly however it is usually
199 *                  called via macros such as TEST_ASSERT, TEST_EQUAL,
200 *                  PSA_ASSERT, etc...
201 *
202 * \note            If the test case was already marked as failed, calling
203 *                  `mbedtls_test_fail( )` again will not overwrite any
204 *                  previous information about the failure.
205 *
206 * \param test      Description of the failure or assertion that failed. This
207 *                  MUST be a string literal.
208 * \param line_no   Line number where the failure originated.
209 * \param filename  Filename where the failure originated.
210 */
211void mbedtls_test_fail(const char *test, int line_no, const char *filename);
212
213/**
214 * \brief           Record the current test case as skipped.
215 *
216 *                  This function can be called directly however it is usually
217 *                  called via the TEST_ASSUME macro.
218 *
219 * \param test      Description of the assumption that caused the test case to
220 *                  be skipped. This MUST be a string literal.
221 * \param line_no   Line number where the test case was skipped.
222 * \param filename  Filename where the test case was skipped.
223 */
224void mbedtls_test_skip(const char *test, int line_no, const char *filename);
225
226/**
227 * \brief           Set the test step number for failure reports.
228 *
229 *                  Call this function to display "step NNN" in addition to the
230 *                  line number and file name if a test fails. Typically the
231 *                  "step number" is the index of a for loop but it can be
232 *                  whatever you want.
233 *
234 * \note            It is not recommended for multiple threads to call this
235 *                  function concurrently - whilst it is entirely thread safe,
236 *                  the order of calls to this function can obviously not be
237 *                  ensured, so unexpected results may occur.
238 *
239 * \param step  The step number to report.
240 */
241void mbedtls_test_set_step(unsigned long step);
242
243/**
244 * \brief           Reset mbedtls_test_info to a ready/starting state.
245 */
246void mbedtls_test_info_reset(void);
247
248#ifdef MBEDTLS_TEST_MUTEX_USAGE
249/**
250 * \brief           Get the test info data mutex.
251 *
252 * \note            This is designed only to be used by threading_helpers to
253 *                  avoid a deadlock, not for general access to this mutex.
254 *
255 * \return          The test info data mutex.
256 */
257mbedtls_threading_mutex_t *mbedtls_test_get_info_mutex(void);
258
259#endif /* MBEDTLS_TEST_MUTEX_USAGE */
260
261/**
262 * \brief Record the current test case as a failure if two integers
263 *                  have a different value.
264 *
265 *                  This function is usually called via the macro
266 *                  #TEST_EQUAL.
267 *
268 * \param test      Description of the failure or assertion that failed. This
269 *                  MUST be a string literal. This normally has the form
270 *                  "EXPR1 == EXPR2" where EXPR1 has the value \p value1
271 *                  and EXPR2 has the value \p value2.
272 * \param line_no   Line number where the failure originated.
273 * \param filename  Filename where the failure originated.
274 * \param value1    The first value to compare.
275 * \param value2    The second value to compare.
276 *
277 * \return          \c 1 if the values are equal, otherwise \c 0.
278 */
279int mbedtls_test_equal(const char *test, int line_no, const char *filename,
280                       unsigned long long value1, unsigned long long value2);
281
282/**
283 * \brief           Record the current test case as a failure based
284 *                  on comparing two unsigned integers.
285 *
286 *                  This function is usually called via the macro
287 *                  #TEST_LE_U.
288 *
289 * \param test      Description of the failure or assertion that failed. This
290 *                  MUST be a string literal. This normally has the form
291 *                  "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
292 *                  and EXPR2 has the value \p value2.
293 * \param line_no   Line number where the failure originated.
294 * \param filename  Filename where the failure originated.
295 * \param value1    The first value to compare.
296 * \param value2    The second value to compare.
297 *
298 * \return          \c 1 if \p value1 <= \p value2, otherwise \c 0.
299 */
300int mbedtls_test_le_u(const char *test, int line_no, const char *filename,
301                      unsigned long long value1, unsigned long long value2);
302
303/**
304 * \brief           Record the current test case as a failure based
305 *                  on comparing two signed integers.
306 *
307 *                  This function is usually called via the macro
308 *                  #TEST_LE_S.
309 *
310 * \param test      Description of the failure or assertion that failed. This
311 *                  MUST be a string literal. This normally has the form
312 *                  "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
313 *                  and EXPR2 has the value \p value2.
314 * \param line_no   Line number where the failure originated.
315 * \param filename  Filename where the failure originated.
316 * \param value1    The first value to compare.
317 * \param value2    The second value to compare.
318 *
319 * \return          \c 1 if \p value1 <= \p value2, otherwise \c 0.
320 */
321int mbedtls_test_le_s(const char *test, int line_no, const char *filename,
322                      long long value1, long long value2);
323
324/**
325 * \brief          This function decodes the hexadecimal representation of
326 *                 data.
327 *
328 * \note           The output buffer can be the same as the input buffer. For
329 *                 any other overlapping of the input and output buffers, the
330 *                 behavior is undefined.
331 *
332 * \param obuf     Output buffer.
333 * \param obufmax  Size in number of bytes of \p obuf.
334 * \param ibuf     Input buffer.
335 * \param len      The number of unsigned char written in \p obuf. This must
336 *                 not be \c NULL.
337 *
338 * \return         \c 0 on success.
339 * \return         \c -1 if the output buffer is too small or the input string
340 *                 is not a valid hexadecimal representation.
341 */
342int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax,
343                          const char *ibuf, size_t *len);
344
345void mbedtls_test_hexify(unsigned char *obuf,
346                         const unsigned char *ibuf,
347                         int len);
348
349/**
350 * \brief Convert hexadecimal digit to an integer.
351 *
352 * \param c        The digit to convert (`'0'` to `'9'`, `'A'` to `'F'` or
353 *                 `'a'` to `'f'`).
354 * \param[out] uc  On success, the value of the digit (0 to 15).
355 *
356 * \return         0 on success, -1 if \p c is not a hexadecimal digit.
357 */
358int mbedtls_test_ascii2uc(const char c, unsigned char *uc);
359
360/**
361 * Allocate and zeroize a buffer.
362 *
363 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
364 *
365 * For convenience, dies if allocation fails.
366 */
367unsigned char *mbedtls_test_zero_alloc(size_t len);
368
369/**
370 * Allocate and fill a buffer from hex data.
371 *
372 * The buffer is sized exactly as needed. This allows to detect buffer
373 * overruns (including overreads) when running the test suite under valgrind.
374 *
375 * If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
376 *
377 * For convenience, dies if allocation fails.
378 */
379unsigned char *mbedtls_test_unhexify_alloc(const char *ibuf, size_t *olen);
380
381int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b,
382                        uint32_t a_len, uint32_t b_len);
383
384#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
385#include "test/fake_external_rng_for_test.h"
386#endif
387
388#if defined(MBEDTLS_TEST_HOOKS)
389/**
390 * \brief   Check that only a pure high-level error code is being combined with
391 *          a pure low-level error code as otherwise the resultant error code
392 *          would be corrupted.
393 *
394 * \note    Both high-level and low-level error codes cannot be greater than
395 *          zero however can be zero. If one error code is zero then the
396 *          other error code is returned even if both codes are zero.
397 *
398 * \note    If the check fails, fail the test currently being run.
399 */
400void mbedtls_test_err_add_check(int high, int low,
401                                const char *file, int line);
402#endif
403
404#endif /* TEST_HELPERS_H */
405