#include "common.h"
#include "mbedtls/bignum.h"
#include "constant_time_internal.h"

Include dependency graph for bignum_core.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	ciL (sizeof(mbedtls_mpi_uint)) /** chars in limb */

#define	biL (ciL << 3) /** bits in limb */

#define	biH (ciL << 2) /** half limb size */

#define	BITS_TO_LIMBS(i) ((i) / biL + ((i) % biL != 0))

#define	CHARS_TO_LIMBS(i) ((i) / ciL + ((i) % ciL != 0))

#define	GET_BYTE(X, i) (((X)[(i) / ciL] >> (((i) % ciL) * 8)) & 0xff)

#define	MBEDTLS_MPI_IS_PUBLIC 0x2a2a2a2a

#define	MBEDTLS_MPI_IS_SECRET 0

Functions
size_t	mbedtls_mpi_core_clz (mbedtls_mpi_uint a)

size_t	mbedtls_mpi_core_bitlen (const mbedtls_mpi_uint *A, size_t A_limbs)

void	mbedtls_mpi_core_bigendian_to_host (mbedtls_mpi_uint *A, size_t A_limbs)

mbedtls_ct_condition_t	mbedtls_mpi_core_uint_le_mpi (mbedtls_mpi_uint min, const mbedtls_mpi_uint *A, size_t A_limbs)
	Compare a machine integer with an MPI.

mbedtls_ct_condition_t	mbedtls_mpi_core_lt_ct (const mbedtls_mpi_uint A, const mbedtls_mpi_uint B, size_t limbs)
	Check if one unsigned MPI is less than another in constant time.

void	mbedtls_mpi_core_cond_assign (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, size_t limbs, mbedtls_ct_condition_t assign)
	Perform a safe conditional copy of an MPI which doesn't reveal whether assignment was done or not.

void	mbedtls_mpi_core_cond_swap (mbedtls_mpi_uint X, mbedtls_mpi_uint Y, size_t limbs, mbedtls_ct_condition_t swap)
	Perform a safe conditional swap of two MPIs which doesn't reveal whether the swap was done or not.

int	mbedtls_mpi_core_read_le (mbedtls_mpi_uint X, size_t X_limbs, const unsigned char input, size_t input_length)

int	mbedtls_mpi_core_read_be (mbedtls_mpi_uint X, size_t X_limbs, const unsigned char input, size_t input_length)

int	mbedtls_mpi_core_write_le (const mbedtls_mpi_uint A, size_t A_limbs, unsigned char output, size_t output_length)

int	mbedtls_mpi_core_write_be (const mbedtls_mpi_uint A, size_t A_limbs, unsigned char output, size_t output_length)

void	mbedtls_mpi_core_shift_r (mbedtls_mpi_uint *X, size_t limbs, size_t count)
	Shift an MPI in-place right by a number of bits.

void	mbedtls_mpi_core_shift_l (mbedtls_mpi_uint *X, size_t limbs, size_t count)
	Shift an MPI in-place left by a number of bits.

mbedtls_mpi_uint	mbedtls_mpi_core_add (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint *B, size_t limbs)
	Add two fixed-size large unsigned integers, returning the carry.

mbedtls_mpi_uint	mbedtls_mpi_core_add_if (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, size_t limbs, unsigned cond)
	Conditional addition of two fixed-size large unsigned integers, returning the carry.

mbedtls_mpi_uint	mbedtls_mpi_core_sub (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint *B, size_t limbs)
	Subtract two fixed-size large unsigned integers, returning the borrow.

mbedtls_mpi_uint	mbedtls_mpi_core_mla (mbedtls_mpi_uint X, size_t X_limbs, const mbedtls_mpi_uint A, size_t A_limbs, mbedtls_mpi_uint b)
	Perform a fixed-size multiply accumulate operation: X += b * A.

void	mbedtls_mpi_core_mul (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, size_t A_limbs, const mbedtls_mpi_uint *B, size_t B_limbs)
	Perform a known-size multiplication.

mbedtls_mpi_uint	mbedtls_mpi_core_montmul_init (const mbedtls_mpi_uint *N)
	Calculate initialisation value for fast Montgomery modular multiplication.

void	mbedtls_mpi_core_montmul (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint B, size_t B_limbs, const mbedtls_mpi_uint N, size_t AN_limbs, mbedtls_mpi_uint mm, mbedtls_mpi_uint *T)
	Montgomery multiplication: X = A * B * R^-1 mod N (HAC 14.36)

int	mbedtls_mpi_core_get_mont_r2_unsafe (mbedtls_mpi X, const mbedtls_mpi N)
	Calculate the square of the Montgomery constant. (Needed for conversion and operations in Montgomery form.)

int	mbedtls_mpi_core_fill_random (mbedtls_mpi_uint X, size_t X_limbs, size_t bytes, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	Fill an integer with a number of random bytes.

int	mbedtls_mpi_core_random (mbedtls_mpi_uint X, mbedtls_mpi_uint min, const mbedtls_mpi_uint N, size_t limbs, int(f_rng)(void , unsigned char , size_t), void p_rng)

size_t	mbedtls_mpi_core_exp_mod_working_limbs (size_t AN_limbs, size_t E_limbs)
	Returns the number of limbs of working memory required for a call to `mbedtls_mpi_core_exp_mod()`.

void	mbedtls_mpi_core_exp_mod_unsafe (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint N, size_t AN_limbs, const mbedtls_mpi_uint E, size_t E_limbs, const mbedtls_mpi_uint RR, mbedtls_mpi_uint T)
	Perform a modular exponentiation with public or secret exponent: X = A^E mod N, where `A` is already in Montgomery form.

void	mbedtls_mpi_core_exp_mod (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint N, size_t AN_limbs, const mbedtls_mpi_uint E, size_t E_limbs, const mbedtls_mpi_uint RR, mbedtls_mpi_uint T)
	Perform a modular exponentiation with secret exponent: X = A^E mod N, where `A` is already in Montgomery form.

mbedtls_mpi_uint	mbedtls_mpi_core_sub_int (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, mbedtls_mpi_uint b, size_t limbs)
	Subtract unsigned integer from known-size large unsigned integers. Return the borrow.

mbedtls_ct_condition_t	mbedtls_mpi_core_check_zero_ct (const mbedtls_mpi_uint *A, size_t limbs)
	Determine if a given MPI has the value `0` in constant time with respect to the value (but not with respect to the number of limbs).

void	mbedtls_mpi_core_to_mont_rep (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint N, size_t AN_limbs, mbedtls_mpi_uint mm, const mbedtls_mpi_uint rr, mbedtls_mpi_uint *T)

void	mbedtls_mpi_core_from_mont_rep (mbedtls_mpi_uint X, const mbedtls_mpi_uint A, const mbedtls_mpi_uint N, size_t AN_limbs, mbedtls_mpi_uint mm, mbedtls_mpi_uint T)

Macro Definition Documentation

◆ biH

#define biH (ciL << 2) /** half limb size */

◆ biL

#define biL (ciL << 3) /** bits in limb */

◆ BITS_TO_LIMBS

#define BITS_TO_LIMBS ( i ) ((i) / biL + ((i) % biL != 0))

◆ CHARS_TO_LIMBS

#define CHARS_TO_LIMBS ( i ) ((i) / ciL + ((i) % ciL != 0))

◆ ciL

#define ciL (sizeof(mbedtls_mpi_uint)) /** chars in limb */

Core bignum functions

This interface should only be used by the legacy bignum module (bignum.h) and the modular bignum modules (bignum_mod.c, bignum_mod_raw.c). All other modules should use the high-level modular bignum interface (bignum_mod.h) or the legacy bignum interface (bignum.h).

This module is about processing non-negative integers with a fixed upper bound that's of the form 2^n-1 where n is a multiple of biL. These can be thought of integers written in base 2^biL with a fixed number of digits. Digits in this base are called limbs. Many operations treat these numbers as the principal representation of a number modulo 2^n or a smaller bound.

The functions in this module obey the following conventions unless explicitly indicated otherwise:

Overflow: some functions indicate overflow from the range [0, 2^n-1] by returning carry parameters, while others operate modulo and so cannot overflow. This should be clear from the function documentation.
Bignum parameters: Bignums are passed as pointers to an array of limbs. A limb has the type mbedtls_mpi_uint. Unless otherwise specified:
- Bignum parameters called A, B, ... are inputs, and are not modified by the function.
- For operations modulo some number, the modulus is called N and is input-only.
- Bignum parameters called X, Y are outputs or input-output. The initial content of output-only parameters is ignored.
- Some functions use different names that reflect traditional naming of operands of certain operations (e.g. divisor/dividend/quotient/remainder).
- T is a temporary storage area. The initial content of such parameter is ignored and the final content is unspecified.
Bignum sizes: bignum sizes are always expressed in limbs. Most functions work on bignums of a given size and take a single limbs parameter that applies to all parameters that are limb arrays. All bignum sizes must be at least 1 and must be significantly less than SIZE_MAX. The behavior if a size is 0 is undefined. The behavior if the total size of all parameters overflows SIZE_MAX is undefined.
Parameter ordering: for bignum parameters, outputs come before inputs. Temporaries come last.
Aliasing: in general, output bignums may be aliased to one or more inputs. As an exception, parameters that are documented as a modulus value may not be aliased to an output. Outputs may not be aliased to one another. Temporaries may not be aliased to any other parameter.
Overlap: apart from aliasing of limb array pointers (where two arguments are equal pointers), overlap is not supported and may result in undefined behavior.
Error handling: This is a low-level module. Functions generally do not try to protect against invalid arguments such as nonsensical sizes or null pointers. Note that some functions that operate on bignums of different sizes have constraints about their size, and violating those constraints may lead to buffer overflows.
Modular representatives: functions that operate modulo N expect all modular inputs to be in the range [0, N - 1] and guarantee outputs in the range [0, N - 1]. If an input is out of range, outputs are fully unspecified, though bignum values out of range should not cause buffer overflows (beware that this is not extensively tested).

◆ GET_BYTE

#define GET_BYTE	(	X,
		i
	)	(((X)[(i) / ciL] >> (((i) % ciL) * 8)) & 0xff)

◆ MBEDTLS_MPI_IS_PUBLIC

#define MBEDTLS_MPI_IS_PUBLIC 0x2a2a2a2a

◆ MBEDTLS_MPI_IS_SECRET

#define MBEDTLS_MPI_IS_SECRET 0

Function Documentation

◆ mbedtls_mpi_core_add()

mbedtls_mpi_uint mbedtls_mpi_core_add	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	B,
		size_t	limbs
	)

Add two fixed-size large unsigned integers, returning the carry.

Calculates A + B where A and B have the same size.

This function operates modulo 2^(biL*limbs) and returns the carry (1 if there was a wraparound, and 0 otherwise).

X may be aliased to A or B.

Parameters

[out]	X	The result of the addition.
[in]	A	Little-endian presentation of the left operand.
[in]	B	Little-endian presentation of the right operand.
	limbs	Number of limbs of `X`, `A` and `B`.

Returns: 1 if A + B >= 2^(biL*limbs), 0 otherwise.

◆ mbedtls_mpi_core_add_if()

mbedtls_mpi_uint mbedtls_mpi_core_add_if	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		size_t	limbs,
		unsigned	cond
	)

Conditional addition of two fixed-size large unsigned integers, returning the carry.

Functionally equivalent to

if( cond )
   X += A;
return carry;

This function operates modulo 2^(biL*limbs).

Parameters

[in,out]	X	The pointer to the (little-endian) array representing the bignum to accumulate onto.
[in]	A	The pointer to the (little-endian) array representing the bignum to conditionally add to `X`. This may be aliased to `X` but may not overlap otherwise.
	limbs	Number of limbs of `X` and `A`.
	cond	Condition bit dictating whether addition should happen or not. This must be `0` or `1`.

Warning: If cond is neither 0 nor 1, the result of this function is unspecified, and the resulting value in X might be neither its original value nor X + A.

Returns: 1 if X + cond * A >= 2^(biL*limbs), 0 otherwise.

◆ mbedtls_mpi_core_bigendian_to_host()

void mbedtls_mpi_core_bigendian_to_host	(	mbedtls_mpi_uint *	A,
		size_t	A_limbs
	)

Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint into the storage form used by mbedtls_mpi.

Parameters

[in,out]	A	The address of the MPI.
	A_limbs	The number of limbs of `A`.

◆ mbedtls_mpi_core_bitlen()

size_t mbedtls_mpi_core_bitlen	(	const mbedtls_mpi_uint *	A,
		size_t	A_limbs
	)

Return the minimum number of bits required to represent the value held in the MPI.

Note: This function returns 0 if all the limbs of A are 0.

Parameters

[in]	A	The address of the MPI.
	A_limbs	The number of limbs of `A`.

Returns: The number of bits in A.

◆ mbedtls_mpi_core_check_zero_ct()

mbedtls_ct_condition_t mbedtls_mpi_core_check_zero_ct	(	const mbedtls_mpi_uint *	A,
		size_t	limbs
	)

Determine if a given MPI has the value 0 in constant time with respect to the value (but not with respect to the number of limbs).

Parameters

[in]	A	The MPI to test.
	limbs	Number of limbs in `A`.

Returns: MBEDTLS_CT_FALSE if A == 0 MBEDTLS_CT_TRUE if A != 0.

◆ mbedtls_mpi_core_clz()

size_t mbedtls_mpi_core_clz ( mbedtls_mpi_uint a )

Count leading zero bits in a given integer.

Warning: The result is undefined if a == 0

Parameters

a	Integer to count leading zero bits.

Returns: The number of leading zero bits in a, if a != 0. If a == 0, the result is undefined.

◆ mbedtls_mpi_core_cond_assign()

void mbedtls_mpi_core_cond_assign	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		size_t	limbs,
		mbedtls_ct_condition_t	assign
	)

Perform a safe conditional copy of an MPI which doesn't reveal whether assignment was done or not.

Parameters

[out]	X	The address of the destination MPI. This must be initialized. Must have enough limbs to store the full value of `A`.
[in]	A	The address of the source MPI. This must be initialized.
	limbs	The number of limbs of `A`.
	assign	The condition deciding whether to perform the assignment or not. Callers will need to use the constant time interface (e.g. `mbedtls_ct_bool()`) to construct this argument.

Note: This function avoids leaking any information about whether the assignment was done or not.

◆ mbedtls_mpi_core_cond_swap()

void mbedtls_mpi_core_cond_swap	(	mbedtls_mpi_uint *	X,
		mbedtls_mpi_uint *	Y,
		size_t	limbs,
		mbedtls_ct_condition_t	swap
	)

Perform a safe conditional swap of two MPIs which doesn't reveal whether the swap was done or not.

Parameters

[in,out]	X	The address of the first MPI. This must be initialized.
[in,out]	Y	The address of the second MPI. This must be initialized.
	limbs	The number of limbs of `X` and `Y`.
	swap	The condition deciding whether to perform the swap or not.

Note: This function avoids leaking any information about whether the swap was done or not.

◆ mbedtls_mpi_core_exp_mod()

void mbedtls_mpi_core_exp_mod	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	N,
		size_t	AN_limbs,
		const mbedtls_mpi_uint *	E,
		size_t	E_limbs,
		const mbedtls_mpi_uint *	RR,
		mbedtls_mpi_uint *	T
	)

Perform a modular exponentiation with secret exponent: X = A^E mod N, where A is already in Montgomery form.

X may be aliased to A, but not to RR or E, even if E_limbs == AN_limbs.

Parameters

[out]	X	The destination MPI, as a little endian array of length `AN_limbs`.
[in]	A	The base MPI, as a little endian array of length `AN_limbs`. Must be in Montgomery form.
[in]	N	The modulus, as a little endian array of length `AN_limbs`.
	AN_limbs	The number of limbs in `X`, `A`, `N`, `RR`.
[in]	E	The exponent, as a little endian array of length `E_limbs`.
	E_limbs	The number of limbs in `E`.
[in]	RR	The precomputed residue of 2^{2*biL} modulo N, as a little endian array of length `AN_limbs`.
[in,out]	T	Temporary storage of at least the number of limbs returned by `mbedtls_mpi_core_exp_mod_working_limbs()`. Its initial content is unused and its final content is indeterminate. It must not alias or otherwise overlap any of the other parameters. It is up to the caller to zeroize `T` when it is no longer needed, and before freeing it if it was dynamically allocated.

◆ mbedtls_mpi_core_exp_mod_unsafe()

void mbedtls_mpi_core_exp_mod_unsafe	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	N,
		size_t	AN_limbs,
		const mbedtls_mpi_uint *	E,
		size_t	E_limbs,
		const mbedtls_mpi_uint *	RR,
		mbedtls_mpi_uint *	T
	)

Perform a modular exponentiation with public or secret exponent: X = A^E mod N, where A is already in Montgomery form.

Warning: This function is not constant time with respect to E (the exponent).

X may be aliased to A, but not to RR or E, even if E_limbs == AN_limbs.

Parameters

[out]	X	The destination MPI, as a little endian array of length `AN_limbs`.
[in]	A	The base MPI, as a little endian array of length `AN_limbs`. Must be in Montgomery form.
[in]	N	The modulus, as a little endian array of length `AN_limbs`.
	AN_limbs	The number of limbs in `X`, `A`, `N`, `RR`.
[in]	E	The exponent, as a little endian array of length `E_limbs`.
	E_limbs	The number of limbs in `E`.
[in]	RR	The precomputed residue of 2^{2*biL} modulo N, as a little endian array of length `AN_limbs`.
[in,out]	T	Temporary storage of at least the number of limbs returned by `mbedtls_mpi_core_exp_mod_working_limbs()`. Its initial content is unused and its final content is indeterminate. It must not alias or otherwise overlap any of the other parameters. It is up to the caller to zeroize `T` when it is no longer needed, and before freeing it if it was dynamically allocated.

◆ mbedtls_mpi_core_exp_mod_working_limbs()

size_t mbedtls_mpi_core_exp_mod_working_limbs	(	size_t	AN_limbs,
		size_t	E_limbs
	)

Returns the number of limbs of working memory required for a call to mbedtls_mpi_core_exp_mod().

Note: This will always be at least mbedtls_mpi_core_montmul_working_limbs(AN_limbs), i.e. sufficient for a call to mbedtls_mpi_core_montmul().

Parameters

AN_limbs	The number of limbs in the input `A` and the modulus `N` (they must be the same size) that will be given to `mbedtls_mpi_core_exp_mod()`.
E_limbs	The number of limbs in the exponent `E` that will be given to `mbedtls_mpi_core_exp_mod()`.

Returns: The number of limbs of working memory required by mbedtls_mpi_core_exp_mod().

◆ mbedtls_mpi_core_fill_random()

int mbedtls_mpi_core_fill_random	(	mbedtls_mpi_uint *	X,
		size_t	X_limbs,
		size_t	bytes,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Fill an integer with a number of random bytes.

Parameters

X	The destination MPI.
X_limbs	The number of limbs of `X`.
bytes	The number of random bytes to generate.
f_rng	The RNG function to use. This must not be `NULL`.
p_rng	The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_BAD_INPUT_DATA if X does not have enough room for bytes bytes.; A negative error code on RNG failure.

Note: The bytes obtained from the RNG are interpreted as a big-endian representation of an MPI; this can be relevant in applications like deterministic ECDSA.

◆ mbedtls_mpi_core_from_mont_rep()

void mbedtls_mpi_core_from_mont_rep	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	N,
		size_t	AN_limbs,
		mbedtls_mpi_uint	mm,
		mbedtls_mpi_uint *	T
	)

Convert an MPI from Montgomery form.

X may be aliased to A, but may not otherwise overlap it.

X may not alias N (it is in canonical form, so must be strictly less than N).

This function is a thin wrapper around mbedtls_mpi_core_montmul() that is an alternative to calling mbedtls_mpi_mod_raw_from_mont_rep() when we don't want to allocate memory.

Parameters

[out]	X	The result of the conversion. Must have the same number of limbs as `A`.
[in]	A	The MPI to convert from Montgomery form. Must have the same number of limbs as the modulus.
[in]	N	The address of the modulus, which gives the size of the base `R` = 2^(biL*N->limbs).
[in]	AN_limbs	The number of limbs in `X`, `A` and `N`.
	mm	The Montgomery constant for `N:` -N^-1 mod 2^biL. This can be determined by calling `mbedtls_mpi_core_montmul_init()`.
[in,out]	T	Temporary storage of size at least `mbedtls_mpi_core_montmul_working_limbs(AN_limbs)` limbs. Its initial content is unused and its final content is indeterminate. It must not alias or otherwise overlap any of the other parameters.

◆ mbedtls_mpi_core_get_mont_r2_unsafe()

int mbedtls_mpi_core_get_mont_r2_unsafe	(	mbedtls_mpi *	X,
		const mbedtls_mpi *	N
	)

Calculate the square of the Montgomery constant. (Needed for conversion and operations in Montgomery form.)

Parameters

[out]	X	A pointer to the result of the calculation of the square of the Montgomery constant: 2^{2nbiL} mod N.
[in]	N	Little-endian presentation of the modulus, which must be odd.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_ALLOC_FAILED if there is not enough space to store the value of Montgomery constant squared.; MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if N modulus is zero.; MBEDTLS_ERR_MPI_NEGATIVE_VALUE if N modulus is negative.

◆ mbedtls_mpi_core_lt_ct()

mbedtls_ct_condition_t mbedtls_mpi_core_lt_ct	(	const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	B,
		size_t	limbs
	)

Check if one unsigned MPI is less than another in constant time.

Parameters

A	The left-hand MPI. This must point to an array of limbs with the same allocated length as `B`.
B	The right-hand MPI. This must point to an array of limbs with the same allocated length as `A`.
limbs	The number of limbs in `A` and `B`. This must not be 0.

Returns: MBEDTLS_CT_TRUE if A is less than B. MBEDTLS_CT_FALSE if A is greater than or equal to B.

◆ mbedtls_mpi_core_mla()

mbedtls_mpi_uint mbedtls_mpi_core_mla	(	mbedtls_mpi_uint *	X,
		size_t	X_limbs,
		const mbedtls_mpi_uint *	A,
		size_t	A_limbs,
		mbedtls_mpi_uint	b
	)

Perform a fixed-size multiply accumulate operation: X += b * A.

X may be aliased to A (when X_limbs == A_limbs), but may not otherwise overlap.

This function operates modulo 2^(biL*X_limbs).

Parameters

[in,out]	X	The pointer to the (little-endian) array representing the bignum to accumulate onto.
	X_limbs	The number of limbs of `X`. This must be at least `A_limbs`.
[in]	A	The pointer to the (little-endian) array representing the bignum to multiply with. This may be aliased to `X` but may not overlap otherwise.
	A_limbs	The number of limbs of `A`.
	b	X scalar to multiply with.

Returns: The carry at the end of the operation.

◆ mbedtls_mpi_core_montmul()

void mbedtls_mpi_core_montmul	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	B,
		size_t	B_limbs,
		const mbedtls_mpi_uint *	N,
		size_t	AN_limbs,
		mbedtls_mpi_uint	mm,
		mbedtls_mpi_uint *	T
	)

Montgomery multiplication: X = A * B * R^-1 mod N (HAC 14.36)

A and B must be in canonical form. That is, < N.

X may be aliased to A or N, or even B (if AN_limbs == B_limbs) but may not overlap any parameters otherwise.

A and B may alias each other, if AN_limbs == B_limbs. They may not alias N (since they must be in canonical form, they cannot == N).

Parameters

[out]	X	The destination MPI, as a little-endian array of length `AN_limbs`. On successful completion, X contains the result of the multiplication `A * B * R^-1` mod N where `R = 2^(biL*AN_limbs)`.
[in]	A	Little-endian presentation of first operand. Must have the same number of limbs as `N`.
[in]	B	Little-endian presentation of second operand.
[in]	B_limbs	The number of limbs in `B`. Must be <= `AN_limbs`.
[in]	N	Little-endian presentation of the modulus. This must be odd, and have exactly the same number of limbs as `A`. It may alias `X`, but must not alias or otherwise overlap any of the other parameters.
[in]	AN_limbs	The number of limbs in `X`, `A` and `N`.
	mm	The Montgomery constant for `N:` -N^-1 mod 2^biL. This can be calculated by `mbedtls_mpi_core_montmul_init()`.
[in,out]	T	Temporary storage of size at least 2*AN_limbs+1 limbs. Its initial content is unused and its final content is indeterminate. It must not alias or otherwise overlap any of the other parameters.

◆ mbedtls_mpi_core_montmul_init()

mbedtls_mpi_uint mbedtls_mpi_core_montmul_init ( const mbedtls_mpi_uint * N )

Calculate initialisation value for fast Montgomery modular multiplication.

Parameters

[in] N Little-endian presentation of the modulus. This must have at least one limb.

Returns: The initialisation value for fast Montgomery modular multiplication

◆ mbedtls_mpi_core_mul()

void mbedtls_mpi_core_mul	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		size_t	A_limbs,
		const mbedtls_mpi_uint *	B,
		size_t	B_limbs
	)

Perform a known-size multiplication.

X may not be aliased to any of the inputs for this function. A may be aliased to B.

Parameters

[out]	X	The pointer to the (little-endian) array to receive the product of `A_limbs` and `B_limbs`. This must be of length `A_limbs` + `B_limbs`.
[in]	A	The pointer to the (little-endian) array representing the first factor.
	A_limbs	The number of limbs in `A`.
[in]	B	The pointer to the (little-endian) array representing the second factor.
	B_limbs	The number of limbs in `B`.

◆ mbedtls_mpi_core_random()

int mbedtls_mpi_core_random	(	mbedtls_mpi_uint *	X,
		mbedtls_mpi_uint	min,
		const mbedtls_mpi_uint *	N,
		size_t	limbs,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

Generate a random number uniformly in a range.

This function generates a random number between min inclusive and N exclusive.

The procedure complies with RFC 6979 §3.3 (deterministic ECDSA) when the RNG is a suitably parametrized instance of HMAC_DRBG and min is 1.

Note: There are N - min possible outputs. The lower bound min can be reached, but the upper bound N cannot.

Parameters

X	The destination MPI, with `limbs` limbs. It must not be aliased with `N` or otherwise overlap it.
min	The minimum value to return.
N	The upper bound of the range, exclusive, with `limbs` limbs. In other words, this is one plus the maximum value to return. `N` must be strictly larger than `min`.
limbs	The number of limbs of `N` and `X`. This must not be 0.
f_rng	The RNG function to use. This must not be `NULL`.
p_rng	The RNG parameter to be passed to `f_rng`.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if the implementation was unable to find a suitable value within a limited number of attempts. This has a negligible probability if N is significantly larger than min, which is the case for all usual cryptographic applications.

◆ mbedtls_mpi_core_read_be()

int mbedtls_mpi_core_read_be	(	mbedtls_mpi_uint *	X,
		size_t	X_limbs,
		const unsigned char *	input,
		size_t	input_length
	)

Import X from unsigned binary data, big-endian.

The MPI needs to have enough limbs to store the full value (including any most significant zero bytes in the input).

Parameters

[out]	X	The address of the MPI. May only be NULL if `X_limbs` is 0 and `input_length` is 0.
	X_limbs	The number of limbs of `X`.
[in]	input	The input buffer to import from. May only be NULL if `input_length` is 0.
	input_length	The length in bytes of `input`.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if X isn't large enough to hold the value in input.

◆ mbedtls_mpi_core_read_le()

int mbedtls_mpi_core_read_le	(	mbedtls_mpi_uint *	X,
		size_t	X_limbs,
		const unsigned char *	input,
		size_t	input_length
	)

Import X from unsigned binary data, little-endian.

The MPI needs to have enough limbs to store the full value (including any most significant zero bytes in the input).

Parameters

[out]	X	The address of the MPI.
	X_limbs	The number of limbs of `X`.
[in]	input	The input buffer to import from.
	input_length	The length bytes of `input`.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if X isn't large enough to hold the value in input.

◆ mbedtls_mpi_core_shift_l()

void mbedtls_mpi_core_shift_l	(	mbedtls_mpi_uint *	X,
		size_t	limbs,
		size_t	count
	)

Shift an MPI in-place left by a number of bits.

                 Shifting by more bits than there are bit positions
                 in \p X will produce an unspecified result.

                 This function's execution time depends on the value
                 of \p count (and of course \p limbs).

Parameters

[in,out]	X	The number to shift.
	limbs	The number of limbs of `X`. This must be at least 1.
	count	The number of bits to shift by.

◆ mbedtls_mpi_core_shift_r()

void mbedtls_mpi_core_shift_r	(	mbedtls_mpi_uint *	X,
		size_t	limbs,
		size_t	count
	)

Shift an MPI in-place right by a number of bits.

                Shifting by more bits than there are bit positions
                in \p X is valid and results in setting \p X to 0.

                This function's execution time depends on the value
                of \p count (and of course \p limbs).

Parameters

[in,out]	X	The number to shift.
	limbs	The number of limbs of `X`. This must be at least 1.
	count	The number of bits to shift by.

◆ mbedtls_mpi_core_sub()

mbedtls_mpi_uint mbedtls_mpi_core_sub	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	B,
		size_t	limbs
	)

Subtract two fixed-size large unsigned integers, returning the borrow.

Calculate A - B where A and B have the same size. This function operates modulo 2^(biL*limbs) and returns the carry (1 if there was a wraparound, i.e. if A < B, and 0 otherwise).

X may be aliased to A or B, or even both, but may not overlap either otherwise.

Parameters

[out]	X	The result of the subtraction.
[in]	A	Little-endian presentation of left operand.
[in]	B	Little-endian presentation of right operand.
	limbs	Number of limbs of `X`, `A` and `B`.

Returns: 1 if A < B. 0 if A >= B.

◆ mbedtls_mpi_core_sub_int()

mbedtls_mpi_uint mbedtls_mpi_core_sub_int	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		mbedtls_mpi_uint	b,
		size_t	limbs
	)

Subtract unsigned integer from known-size large unsigned integers. Return the borrow.

Parameters

[out]	X	The result of the subtraction.
[in]	A	The left operand.
	b	The unsigned scalar to subtract.
	limbs	Number of limbs of `X` and `A`.

Returns: 1 if A < b. 0 if A >= b.

◆ mbedtls_mpi_core_to_mont_rep()

void mbedtls_mpi_core_to_mont_rep	(	mbedtls_mpi_uint *	X,
		const mbedtls_mpi_uint *	A,
		const mbedtls_mpi_uint *	N,
		size_t	AN_limbs,
		mbedtls_mpi_uint	mm,
		const mbedtls_mpi_uint *	rr,
		mbedtls_mpi_uint *	T
	)

Convert an MPI into Montgomery form.

X may be aliased to A, but may not otherwise overlap it.

X may not alias N (it is in canonical form, so must be strictly less than N). Nor may it alias or overlap rr (this is unlikely to be required in practice.)

This function is a thin wrapper around mbedtls_mpi_core_montmul() that is an alternative to calling mbedtls_mpi_mod_raw_to_mont_rep() when we don't want to allocate memory.

Parameters

[out]	X	The result of the conversion. Must have the same number of limbs as `A`.
[in]	A	The MPI to convert into Montgomery form. Must have the same number of limbs as the modulus.
[in]	N	The address of the modulus, which gives the size of the base `R` = 2^(biL*N->limbs).
[in]	AN_limbs	The number of limbs in `X`, `A`, `N` and `rr`.
	mm	The Montgomery constant for `N:` -N^-1 mod 2^biL. This can be determined by calling `mbedtls_mpi_core_montmul_init()`.
[in]	rr	The residue for `2^{2nbiL} mod N`.
[in,out]	T	Temporary storage of size at least `mbedtls_mpi_core_montmul_working_limbs(AN_limbs)` limbs. Its initial content is unused and its final content is indeterminate. It must not alias or otherwise overlap any of the other parameters.

◆ mbedtls_mpi_core_uint_le_mpi()

mbedtls_ct_condition_t mbedtls_mpi_core_uint_le_mpi	(	mbedtls_mpi_uint	min,
		const mbedtls_mpi_uint *	A,
		size_t	A_limbs
	)

Compare a machine integer with an MPI.

           This function operates in constant time with respect
           to the values of \p min and \p A.

Parameters

	min	A machine integer.
[in]	A	An MPI.
	A_limbs	The number of limbs of `A`. This must be at least 1.

Returns: MBEDTLS_CT_TRUE if min is less than or equal to A, otherwise MBEDTLS_CT_FALSE.

◆ mbedtls_mpi_core_write_be()

int mbedtls_mpi_core_write_be	(	const mbedtls_mpi_uint *	A,
		size_t	A_limbs,
		unsigned char *	output,
		size_t	output_length
	)

Export A into unsigned binary data, big-endian.

Note: If output is shorter than A the export is still successful if the value held in A fits in the buffer (that is, if enough of the most significant bytes of A are 0).

Parameters

[in]	A	The address of the MPI.
	A_limbs	The number of limbs of `A`.
[out]	output	The output buffer to export to.
	output_length	The length in bytes of `output`.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if output isn't large enough to hold the value of A.

◆ mbedtls_mpi_core_write_le()

int mbedtls_mpi_core_write_le	(	const mbedtls_mpi_uint *	A,
		size_t	A_limbs,
		unsigned char *	output,
		size_t	output_length
	)

Export A into unsigned binary data, little-endian.

Note: If output is shorter than A the export is still successful if the value held in A fits in the buffer (that is, if enough of the most significant bytes of A are 0).

Parameters

[in]	A	The address of the MPI.
	A_limbs	The number of limbs of `A`.
[out]	output	The output buffer to export to.
	output_length	The length in bytes of `output`.

Returns: 0 if successful.; MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if output isn't large enough to hold the value of A.

Macros

Functions

Macro Definition Documentation

◆ biH

◆ biL

◆ BITS_TO_LIMBS

◆ CHARS_TO_LIMBS

◆ ciL

◆ GET_BYTE

◆ MBEDTLS_MPI_IS_PUBLIC

◆ MBEDTLS_MPI_IS_SECRET

Function Documentation

◆ mbedtls_mpi_core_add()

◆ mbedtls_mpi_core_add_if()

◆ mbedtls_mpi_core_bigendian_to_host()

◆ mbedtls_mpi_core_bitlen()

◆ mbedtls_mpi_core_check_zero_ct()

◆ mbedtls_mpi_core_clz()

◆ mbedtls_mpi_core_cond_assign()

◆ mbedtls_mpi_core_cond_swap()

◆ mbedtls_mpi_core_exp_mod()

◆ mbedtls_mpi_core_exp_mod_unsafe()

◆ mbedtls_mpi_core_exp_mod_working_limbs()

◆ mbedtls_mpi_core_fill_random()

◆ mbedtls_mpi_core_from_mont_rep()

◆ mbedtls_mpi_core_get_mont_r2_unsafe()

◆ mbedtls_mpi_core_lt_ct()

◆ mbedtls_mpi_core_mla()

◆ mbedtls_mpi_core_montmul()

◆ mbedtls_mpi_core_montmul_init()

◆ mbedtls_mpi_core_mul()

◆ mbedtls_mpi_core_random()

◆ mbedtls_mpi_core_read_be()

◆ mbedtls_mpi_core_read_le()

◆ mbedtls_mpi_core_shift_l()

◆ mbedtls_mpi_core_shift_r()

◆ mbedtls_mpi_core_sub()

◆ mbedtls_mpi_core_sub_int()

◆ mbedtls_mpi_core_to_mont_rep()

◆ mbedtls_mpi_core_uint_le_mpi()

◆ mbedtls_mpi_core_write_be()

◆ mbedtls_mpi_core_write_le()