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