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 */
43int 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 */
62int 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 */
71void 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 calls
81 *   mbedtls_test_increment_case_uses_negative_0().
82 * - The size of the result is exactly the minimum number of limbs needed to fit
83 *   the digits in the input. In particular, this function constructs a bignum
84 *   with 0 limbs for an empty string, and a bignum with leading 0 limbs if the
85 *   string has sufficiently many leading 0 digits. This is important so that
86 *   the "0 (null)" and "0 (1 limb)" and "leading zeros" test cases do what they
87 *   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 */
94int mbedtls_test_read_mpi(mbedtls_mpi *X, const char *s);
95
96#endif /* MBEDTLS_BIGNUM_C */
97
98#endif /* TEST_BIGNUM_HELPERS_H */
99