diff options
Diffstat (limited to 'tests/include/test/helpers.h')
| -rw-r--r-- | tests/include/test/helpers.h | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/tests/include/test/helpers.h b/tests/include/test/helpers.h new file mode 100644 index 00000000000..d08100f1587 --- /dev/null +++ b/tests/include/test/helpers.h @@ -0,0 +1,404 @@ +/** + * \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(__SANITIZE_THREAD__) /* gcc -fsanitize-thread */ +# define MBEDTLS_TEST_HAVE_TSAN +#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 + +#include "test/threading_helpers.h" + +#if defined(MBEDTLS_TEST_MUTEX_USAGE) +#include "mbedtls/threading.h" +#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 It is not recommended for multiple threads to call this + * function concurrently - 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 It is not recommended for multiple threads to call this + * function concurrently - 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_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 */ |