mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-01-17 07:17:12 +00:00
79e2e5d2d0
These functions are thread safe, but using them from within multiple threads at the same time may not have the intended effect, given order cannot be guaranteed. Also, standardise header comment formatting. Signed-off-by: Paul Elliott <paul.elliott@arm.com>
419 lines
14 KiB
C
419 lines
14 KiB
C
/**
|
|
* \file helpers.h
|
|
*
|
|
* \brief This file contains the prototypes of helper functions for the
|
|
* purpose of testing.
|
|
*/
|
|
|
|
/*
|
|
* Copyright The Mbed TLS Contributors
|
|
* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
|
|
*/
|
|
|
|
#ifndef TEST_HELPERS_H
|
|
#define TEST_HELPERS_H
|
|
|
|
/* Most fields of publicly available structs are private and are wrapped with
|
|
* MBEDTLS_PRIVATE macro. This define allows tests to access the private fields
|
|
* directly (without using the MBEDTLS_PRIVATE wrapper). */
|
|
#define MBEDTLS_ALLOW_PRIVATE_ACCESS
|
|
|
|
#include "mbedtls/build_info.h"
|
|
|
|
#if defined(__SANITIZE_ADDRESS__) /* gcc -fsanitize=address */
|
|
# define MBEDTLS_TEST_HAVE_ASAN
|
|
#endif
|
|
#if defined(__has_feature)
|
|
# if __has_feature(address_sanitizer) /* clang -fsanitize=address */
|
|
# define MBEDTLS_TEST_HAVE_ASAN
|
|
# endif
|
|
# if __has_feature(memory_sanitizer) /* clang -fsanitize=memory */
|
|
# define MBEDTLS_TEST_HAVE_MSAN
|
|
# endif
|
|
# if __has_feature(thread_sanitizer) /* clang -fsanitize=thread */
|
|
# define MBEDTLS_TEST_HAVE_TSAN
|
|
# endif
|
|
#endif
|
|
|
|
#if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \
|
|
defined(MBEDTLS_TEST_HOOKS)
|
|
#include "mbedtls/threading.h"
|
|
#define MBEDTLS_TEST_MUTEX_USAGE
|
|
#endif
|
|
|
|
#include "mbedtls/platform.h"
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#if defined(MBEDTLS_BIGNUM_C)
|
|
#include "mbedtls/bignum.h"
|
|
#endif
|
|
|
|
/** The type of test case arguments that contain binary data. */
|
|
typedef struct data_tag {
|
|
uint8_t *x;
|
|
uint32_t len;
|
|
} data_t;
|
|
|
|
typedef enum {
|
|
MBEDTLS_TEST_RESULT_SUCCESS = 0,
|
|
MBEDTLS_TEST_RESULT_FAILED,
|
|
MBEDTLS_TEST_RESULT_SKIPPED
|
|
} mbedtls_test_result_t;
|
|
|
|
#define MBEDTLS_TEST_LINE_LENGTH 76
|
|
|
|
typedef struct {
|
|
mbedtls_test_result_t result;
|
|
const char *test;
|
|
const char *filename;
|
|
int line_no;
|
|
unsigned long step;
|
|
char line1[MBEDTLS_TEST_LINE_LENGTH];
|
|
char line2[MBEDTLS_TEST_LINE_LENGTH];
|
|
#if defined(MBEDTLS_TEST_MUTEX_USAGE)
|
|
const char *mutex_usage_error;
|
|
#endif
|
|
#if defined(MBEDTLS_BIGNUM_C)
|
|
unsigned case_uses_negative_0;
|
|
#endif
|
|
}
|
|
mbedtls_test_info_t;
|
|
|
|
/**
|
|
* \brief Get the current test result status
|
|
*
|
|
* \return The current test result status
|
|
*/
|
|
mbedtls_test_result_t mbedtls_test_get_result(void);
|
|
|
|
/**
|
|
* \brief Get the current test name/description
|
|
*
|
|
* \return The current test name/description
|
|
*/
|
|
const char *mbedtls_test_get_test(void);
|
|
|
|
/**
|
|
* \brief Get the current test filename
|
|
*
|
|
* \return The current test filename
|
|
*/
|
|
const char *mbedtls_get_test_filename(void);
|
|
|
|
/**
|
|
* \brief Get the current test file line number (for failure / skip)
|
|
*
|
|
* \return The current test file line number (for failure / skip)
|
|
*/
|
|
int mbedtls_test_get_line_no(void);
|
|
|
|
/**
|
|
* \brief Increment the current test step.
|
|
*
|
|
* \note Calling this function from within multiple threads at the
|
|
* same time is not recommended - whilst it is entirely thread
|
|
* safe, the order of calls to this function can obviously not
|
|
* be ensured, so unexpected results may occur.
|
|
*/
|
|
void mbedtls_test_increment_step(void);
|
|
|
|
/**
|
|
* \brief Get the current test step
|
|
*
|
|
* \return The current test step
|
|
*/
|
|
unsigned long mbedtls_test_get_step(void);
|
|
|
|
/**
|
|
* \brief Get the current test line buffer 1
|
|
*
|
|
* \param line Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH,
|
|
* which will have line buffer 1 copied to it.
|
|
*/
|
|
void mbedtls_test_get_line1(char *line);
|
|
|
|
/**
|
|
* \brief Get the current test line buffer 2
|
|
*
|
|
* \param line Buffer of minimum size \c MBEDTLS_TEST_LINE_LENGTH,
|
|
* which will have line buffer 1 copied to it.
|
|
*/
|
|
void mbedtls_test_get_line2(char *line);
|
|
|
|
#if defined(MBEDTLS_TEST_MUTEX_USAGE)
|
|
/**
|
|
* \brief Get the current mutex usage error message
|
|
*
|
|
* \return The current mutex error message (may be NULL if no error)
|
|
*/
|
|
const char *mbedtls_test_get_mutex_usage_error(void);
|
|
|
|
/**
|
|
* \brief Set the current mutex usage error message
|
|
*
|
|
* \note This will only set the mutex error message if one has not
|
|
* already been set, or if we are clearing the message (msg is
|
|
* NULL)
|
|
*
|
|
* \param msg Error message to set (can be NULL to clear)
|
|
*/
|
|
void mbedtls_test_set_mutex_usage_error(const char *msg);
|
|
#endif
|
|
|
|
#if defined(MBEDTLS_BIGNUM_C)
|
|
|
|
/**
|
|
* \brief Get whether the current test is a bignum test that uses
|
|
* negative zero.
|
|
*
|
|
* \return non zero if the current test uses bignum negative zero.
|
|
*/
|
|
unsigned mbedtls_test_get_case_uses_negative_0(void);
|
|
|
|
/**
|
|
* \brief Indicate that the current test uses bignum negative zero.
|
|
*
|
|
* \note This function is called if the current test case had an
|
|
* input parsed with mbedtls_test_read_mpi() that is a negative
|
|
* 0 (`"-"`, `"-0"`, `"-00"`, etc., constructing a result with
|
|
* the sign bit set to -1 and the value being all-limbs-0,
|
|
* which is not a valid representation in #mbedtls_mpi but is
|
|
* tested for robustness). *
|
|
*/
|
|
void mbedtls_test_increment_case_uses_negative_0(void);
|
|
#endif
|
|
|
|
int mbedtls_test_platform_setup(void);
|
|
void mbedtls_test_platform_teardown(void);
|
|
|
|
/**
|
|
* \brief Record the current test case as a failure.
|
|
*
|
|
* This function can be called directly however it is usually
|
|
* called via macros such as TEST_ASSERT, TEST_EQUAL,
|
|
* PSA_ASSERT, etc...
|
|
*
|
|
* \note If the test case was already marked as failed, calling
|
|
* `mbedtls_test_fail( )` again will not overwrite any
|
|
* previous information about the failure.
|
|
*
|
|
* \param test Description of the failure or assertion that failed. This
|
|
* MUST be a string literal.
|
|
* \param line_no Line number where the failure originated.
|
|
* \param filename Filename where the failure originated.
|
|
*/
|
|
void mbedtls_test_fail(const char *test, int line_no, const char *filename);
|
|
|
|
/**
|
|
* \brief Record the current test case as skipped.
|
|
*
|
|
* This function can be called directly however it is usually
|
|
* called via the TEST_ASSUME macro.
|
|
*
|
|
* \param test Description of the assumption that caused the test case to
|
|
* be skipped. This MUST be a string literal.
|
|
* \param line_no Line number where the test case was skipped.
|
|
* \param filename Filename where the test case was skipped.
|
|
*/
|
|
void mbedtls_test_skip(const char *test, int line_no, const char *filename);
|
|
|
|
/**
|
|
* \brief Set the test step number for failure reports.
|
|
*
|
|
* Call this function to display "step NNN" in addition to the
|
|
* line number and file name if a test fails. Typically the
|
|
* "step number" is the index of a for loop but it can be
|
|
* whatever you want.
|
|
*
|
|
* \note Calling this function from a within multiple threads at the
|
|
* same time is not recommended - whilst it is entirely thread
|
|
* safe, the order of calls to this function can obviously not
|
|
* be ensured, so unexpected results may occur.
|
|
*
|
|
* \param step The step number to report.
|
|
*/
|
|
void mbedtls_test_set_step(unsigned long step);
|
|
|
|
/**
|
|
* \brief Reset mbedtls_test_info to a ready/starting state.
|
|
*/
|
|
void mbedtls_test_info_reset(void);
|
|
|
|
#ifdef MBEDTLS_TEST_MUTEX_USAGE
|
|
/**
|
|
* \brief Get the test info data mutex.
|
|
*
|
|
* \note This is designed only to be used by threading_helpers to
|
|
* avoid a deadlock, not for general access to this mutex.
|
|
*
|
|
* \return The test info data mutex.
|
|
*/
|
|
mbedtls_threading_mutex_t *mbedtls_test_get_info_mutex(void);
|
|
|
|
#endif /* MBEDTLS_TEST_MUTEX_USAGE */
|
|
|
|
/**
|
|
* \brief Record the current test case as a failure if two integers
|
|
* have a different value.
|
|
*
|
|
* This function is usually called via the macro
|
|
* #TEST_EQUAL.
|
|
*
|
|
* \param test Description of the failure or assertion that failed. This
|
|
* MUST be a string literal. This normally has the form
|
|
* "EXPR1 == EXPR2" where EXPR1 has the value \p value1
|
|
* and EXPR2 has the value \p value2.
|
|
* \param line_no Line number where the failure originated.
|
|
* \param filename Filename where the failure originated.
|
|
* \param value1 The first value to compare.
|
|
* \param value2 The second value to compare.
|
|
*
|
|
* \return \c 1 if the values are equal, otherwise \c 0.
|
|
*/
|
|
int mbedtls_test_equal(const char *test, int line_no, const char *filename,
|
|
unsigned long long value1, unsigned long long value2);
|
|
|
|
/**
|
|
* \brief Record the current test case as a failure based
|
|
* on comparing two unsigned integers.
|
|
*
|
|
* This function is usually called via the macro
|
|
* #TEST_LE_U.
|
|
*
|
|
* \param test Description of the failure or assertion that failed. This
|
|
* MUST be a string literal. This normally has the form
|
|
* "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
|
|
* and EXPR2 has the value \p value2.
|
|
* \param line_no Line number where the failure originated.
|
|
* \param filename Filename where the failure originated.
|
|
* \param value1 The first value to compare.
|
|
* \param value2 The second value to compare.
|
|
*
|
|
* \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
|
|
*/
|
|
int mbedtls_test_le_u(const char *test, int line_no, const char *filename,
|
|
unsigned long long value1, unsigned long long value2);
|
|
|
|
/**
|
|
* \brief Record the current test case as a failure based
|
|
* on comparing two signed integers.
|
|
*
|
|
* This function is usually called via the macro
|
|
* #TEST_LE_S.
|
|
*
|
|
* \param test Description of the failure or assertion that failed. This
|
|
* MUST be a string literal. This normally has the form
|
|
* "EXPR1 <= EXPR2" where EXPR1 has the value \p value1
|
|
* and EXPR2 has the value \p value2.
|
|
* \param line_no Line number where the failure originated.
|
|
* \param filename Filename where the failure originated.
|
|
* \param value1 The first value to compare.
|
|
* \param value2 The second value to compare.
|
|
*
|
|
* \return \c 1 if \p value1 <= \p value2, otherwise \c 0.
|
|
*/
|
|
int mbedtls_test_le_s(const char *test, int line_no, const char *filename,
|
|
long long value1, long long value2);
|
|
|
|
/**
|
|
* \brief This function decodes the hexadecimal representation of
|
|
* data.
|
|
*
|
|
* \note The output buffer can be the same as the input buffer. For
|
|
* any other overlapping of the input and output buffers, the
|
|
* behavior is undefined.
|
|
*
|
|
* \param obuf Output buffer.
|
|
* \param obufmax Size in number of bytes of \p obuf.
|
|
* \param ibuf Input buffer.
|
|
* \param len The number of unsigned char written in \p obuf. This must
|
|
* not be \c NULL.
|
|
*
|
|
* \return \c 0 on success.
|
|
* \return \c -1 if the output buffer is too small or the input string
|
|
* is not a valid hexadecimal representation.
|
|
*/
|
|
int mbedtls_test_unhexify(unsigned char *obuf, size_t obufmax,
|
|
const char *ibuf, size_t *len);
|
|
|
|
void mbedtls_test_hexify(unsigned char *obuf,
|
|
const unsigned char *ibuf,
|
|
int len);
|
|
|
|
/**
|
|
* \brief Convert hexadecimal digit to an integer.
|
|
*
|
|
* \param c The digit to convert (`'0'` to `'9'`, `'A'` to `'F'` or
|
|
* `'a'` to `'f'`).
|
|
* \param[out] uc On success, the value of the digit (0 to 15).
|
|
*
|
|
* \return 0 on success, -1 if \p c is not a hexadecimal digit.
|
|
*/
|
|
int mbedtls_test_ascii2uc(const char c, unsigned char *uc);
|
|
|
|
/**
|
|
* Allocate and zeroize a buffer.
|
|
*
|
|
* If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
|
|
*
|
|
* For convenience, dies if allocation fails.
|
|
*/
|
|
unsigned char *mbedtls_test_zero_alloc(size_t len);
|
|
|
|
/**
|
|
* Allocate and fill a buffer from hex data.
|
|
*
|
|
* The buffer is sized exactly as needed. This allows to detect buffer
|
|
* overruns (including overreads) when running the test suite under valgrind.
|
|
*
|
|
* If the size if zero, a pointer to a zeroized 1-byte buffer is returned.
|
|
*
|
|
* For convenience, dies if allocation fails.
|
|
*/
|
|
unsigned char *mbedtls_test_unhexify_alloc(const char *ibuf, size_t *olen);
|
|
|
|
int mbedtls_test_hexcmp(uint8_t *a, uint8_t *b,
|
|
uint32_t a_len, uint32_t b_len);
|
|
|
|
#if defined(MBEDTLS_PSA_CRYPTO_C) && defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
|
|
#include "test/fake_external_rng_for_test.h"
|
|
#endif
|
|
|
|
#if defined(MBEDTLS_TEST_MUTEX_USAGE)
|
|
/**
|
|
* Activate the mutex usage verification framework. See threading_helpers.c for
|
|
* information.
|
|
* */
|
|
void mbedtls_test_mutex_usage_init(void);
|
|
|
|
/**
|
|
* Deactivate the mutex usage verification framework. See threading_helpers.c
|
|
* for information.
|
|
*/
|
|
void mbedtls_test_mutex_usage_end(void);
|
|
|
|
/** Call this function after executing a test case to check for mutex usage
|
|
* errors. */
|
|
void mbedtls_test_mutex_usage_check(void);
|
|
#endif /* MBEDTLS_TEST_MUTEX_USAGE */
|
|
|
|
#if defined(MBEDTLS_TEST_HOOKS)
|
|
/**
|
|
* \brief Check that only a pure high-level error code is being combined with
|
|
* a pure low-level error code as otherwise the resultant error code
|
|
* would be corrupted.
|
|
*
|
|
* \note Both high-level and low-level error codes cannot be greater than
|
|
* zero however can be zero. If one error code is zero then the
|
|
* other error code is returned even if both codes are zero.
|
|
*
|
|
* \note If the check fails, fail the test currently being run.
|
|
*/
|
|
void mbedtls_test_err_add_check(int high, int low,
|
|
const char *file, int line);
|
|
#endif
|
|
|
|
#endif /* TEST_HELPERS_H */
|