1 /** 2 * \file bignum_helpers.h 3 * 4 * \brief This file contains the prototypes of helper functions for 5 * bignum-related 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_BIGNUM_HELPERS_H 14 #define TEST_BIGNUM_HELPERS_H 15 16 #include <mbedtls/build_info.h> 17 18 #if defined(MBEDTLS_BIGNUM_C) 19 20 #include <mbedtls/bignum.h> 21 #include <bignum_mod.h> 22 23 /** Allocate and populate a core MPI from a test case argument. 24 * 25 * This function allocates exactly as many limbs as necessary to fit 26 * the length of the input. In other words, it preserves leading zeros. 27 * 28 * The limb array is allocated with mbedtls_calloc() and must later be 29 * freed with mbedtls_free(). 30 * 31 * \param[in,out] pX The address where a pointer to the allocated limb 32 * array will be stored. 33 * \c *pX must be null on entry. 34 * On exit, \c *pX is null on error or if the number 35 * of limbs is 0. 36 * \param[out] plimbs The address where the number of limbs will be stored. 37 * \param[in] input The test argument to read. 38 * It is interpreted as a hexadecimal representation 39 * of a non-negative integer. 40 * 41 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 42 */ 43 int mbedtls_test_read_mpi_core(mbedtls_mpi_uint **pX, size_t *plimbs, 44 const char *input); 45 46 /** Read a modulus from a hexadecimal string. 47 * 48 * This function allocates exactly as many limbs as necessary to fit 49 * the length of the input. In other words, it preserves leading zeros. 50 * 51 * The limb array is allocated with mbedtls_calloc() and must later be 52 * freed with mbedtls_free(). You can do that by calling 53 * mbedtls_test_mpi_mod_modulus_free_with_limbs(). 54 * 55 * \param[in,out] N A modulus structure. It must be initialized, but 56 * not set up. 57 * \param[in] s The null-terminated hexadecimal string to read from. 58 * \param int_rep The desired representation of residues. 59 * 60 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 61 */ 62 int mbedtls_test_read_mpi_modulus(mbedtls_mpi_mod_modulus *N, 63 const char *s, 64 mbedtls_mpi_mod_rep_selector int_rep); 65 66 /** Free a modulus and its limbs. 67 * 68 * \param[in] N A modulus structure such that there is no other 69 * reference to `N->p`. 70 */ 71 void mbedtls_test_mpi_mod_modulus_free_with_limbs(mbedtls_mpi_mod_modulus *N); 72 73 /** Read an MPI from a hexadecimal string. 74 * 75 * Like mbedtls_mpi_read_string(), but with tighter guarantees around 76 * edge cases. 77 * 78 * - This function guarantees that if \p s begins with '-' then the sign 79 * bit of the result will be negative, even if the value is 0. 80 * When this function encounters such a "negative 0", it 81 * increments #mbedtls_test_case_uses_negative_0. 82 * - The size of the result is exactly the minimum number of limbs needed 83 * to fit the digits in the input. In particular, this function constructs 84 * a bignum with 0 limbs for an empty string, and a bignum with leading 0 85 * limbs if the string has sufficiently many leading 0 digits. 86 * This is important so that the "0 (null)" and "0 (1 limb)" and 87 * "leading zeros" test cases do what they claim. 88 * 89 * \param[out] X The MPI object to populate. It must be initialized. 90 * \param[in] s The null-terminated hexadecimal string to read from. 91 * 92 * \return \c 0 on success, an \c MBEDTLS_ERR_MPI_xxx error code otherwise. 93 */ 94 int mbedtls_test_read_mpi(mbedtls_mpi *X, const char *s); 95 96 /** Nonzero if the current test case had an input parsed with 97 * mbedtls_test_read_mpi() that is a negative 0 (`"-"`, `"-0"`, `"-00"`, etc., 98 * constructing a result with the sign bit set to -1 and the value being 99 * all-limbs-0, which is not a valid representation in #mbedtls_mpi but is 100 * tested for robustness). 101 */ 102 extern unsigned mbedtls_test_case_uses_negative_0; 103 104 #endif /* MBEDTLS_BIGNUM_C */ 105 106 #endif /* TEST_BIGNUM_HELPERS_H */ 107
