Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

bignum.h File Reference

bignum.h File Reference

Multi-precision integer library. More...

Go to the source code of this file.

Data Structures

struct  mbedtls_mpi
 MPI structure. More...

Typedefs

typedef struct mbedtls_mpi mbedtls_mpi
 MPI structure.

Enumerations

enum  mbedtls_mpi_gen_prime_flag_t { MBEDTLS_MPI_GEN_PRIME_FLAG_DH = 0x0001, MBEDTLS_MPI_GEN_PRIME_FLAG_LOW_ERR = 0x0002 }
 

Flags for mbedtls_mpi_gen_prime()

More...

Functions

void mbedtls_mpi_init (mbedtls_mpi *X)
 Initialize an MPI context.
void mbedtls_mpi_free (mbedtls_mpi *X)
 This function frees the components of an MPI context.
int mbedtls_mpi_grow (mbedtls_mpi *X, size_t nblimbs)
 Enlarge an MPI to the specified number of limbs.
int mbedtls_mpi_shrink (mbedtls_mpi *X, size_t nblimbs)
 This function resizes an MPI downwards, keeping at least the specified number of limbs.
int mbedtls_mpi_copy (mbedtls_mpi *X, const mbedtls_mpi *Y)
 Make a copy of an MPI.
void mbedtls_mpi_swap (mbedtls_mpi *X, mbedtls_mpi *Y)
 Swap the contents of two MPIs.
int mbedtls_mpi_safe_cond_assign (mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign)
 Perform a safe conditional copy of MPI which doesn't reveal whether the condition was true or not.
int mbedtls_mpi_safe_cond_swap (mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign)
 Perform a safe conditional swap which doesn't reveal whether the condition was true or not.
int mbedtls_mpi_lset (mbedtls_mpi *X, mbedtls_mpi_sint z)
 Store integer value in MPI.
int mbedtls_mpi_get_bit (const mbedtls_mpi *X, size_t pos)
 Get a specific bit from an MPI.
int mbedtls_mpi_set_bit (mbedtls_mpi *X, size_t pos, unsigned char val)
 Modify a specific bit in an MPI.
size_t mbedtls_mpi_lsb (const mbedtls_mpi *X)
 Return the number of bits of value 0 before the least significant bit of value 1.
size_t mbedtls_mpi_bitlen (const mbedtls_mpi *X)
 Return the number of bits up to and including the most significant bit of value 1.
size_t mbedtls_mpi_size (const mbedtls_mpi *X)
 Return the total size of an MPI value in bytes.
int mbedtls_mpi_read_string (mbedtls_mpi *X, int radix, const char *s)
 Import an MPI from an ASCII string.
int mbedtls_mpi_write_string (const mbedtls_mpi *X, int radix, char *buf, size_t buflen, size_t *olen)
 Export an MPI to an ASCII string.
int mbedtls_mpi_read_file (mbedtls_mpi *X, int radix, FILE *fin)
 Read an MPI from a line in an opened file.
int mbedtls_mpi_write_file (const char *p, const mbedtls_mpi *X, int radix, FILE *fout)
 Export an MPI into an opened file.
int mbedtls_mpi_read_binary (mbedtls_mpi *X, const unsigned char *buf, size_t buflen)
 Import an MPI from unsigned big endian binary data.
int mbedtls_mpi_read_binary_le (mbedtls_mpi *X, const unsigned char *buf, size_t buflen)
 Import X from unsigned binary data, little endian.
int mbedtls_mpi_write_binary (const mbedtls_mpi *X, unsigned char *buf, size_t buflen)
 Export X into unsigned binary data, big endian.
int mbedtls_mpi_write_binary_le (const mbedtls_mpi *X, unsigned char *buf, size_t buflen)
 Export X into unsigned binary data, little endian.
int mbedtls_mpi_shift_l (mbedtls_mpi *X, size_t count)
 Perform a left-shift on an MPI: X <<= count.
int mbedtls_mpi_shift_r (mbedtls_mpi *X, size_t count)
 Perform a right-shift on an MPI: X >>= count.
int mbedtls_mpi_cmp_abs (const mbedtls_mpi *X, const mbedtls_mpi *Y)
 Compare the absolute values of two MPIs.
int mbedtls_mpi_cmp_mpi (const mbedtls_mpi *X, const mbedtls_mpi *Y)
 Compare two MPIs.
int mbedtls_mpi_cmp_int (const mbedtls_mpi *X, mbedtls_mpi_sint z)
 Compare an MPI with an integer.
int mbedtls_mpi_add_abs (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform an unsigned addition of MPIs: X = |A| + |B|.
int mbedtls_mpi_sub_abs (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform an unsigned subtraction of MPIs: X = |A| - |B|.
int mbedtls_mpi_add_mpi (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform a signed addition of MPIs: X = A + B.
int mbedtls_mpi_sub_mpi (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform a signed subtraction of MPIs: X = A - B.
int mbedtls_mpi_add_int (mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b)
 Perform a signed addition of an MPI and an integer: X = A + b.
int mbedtls_mpi_sub_int (mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b)
 Perform a signed subtraction of an MPI and an integer: X = A - b.
int mbedtls_mpi_mul_mpi (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform a multiplication of two MPIs: X = A * B.
int mbedtls_mpi_mul_int (mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_uint b)
 Perform a multiplication of an MPI with an unsigned integer: X = A * b.
int mbedtls_mpi_div_mpi (mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform a division with remainder of two MPIs: A = Q * B + R.
int mbedtls_mpi_div_int (mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, mbedtls_mpi_sint b)
 Perform a division with remainder of an MPI by an integer: A = Q * b + R.
int mbedtls_mpi_mod_mpi (mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Perform a modular reduction.
int mbedtls_mpi_mod_int (mbedtls_mpi_uint *r, const mbedtls_mpi *A, mbedtls_mpi_sint b)
 Perform a modular reduction with respect to an integer.
int mbedtls_mpi_exp_mod (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR)
 Perform a sliding-window exponentiation: X = A^E mod N.
int mbedtls_mpi_fill_random (mbedtls_mpi *X, size_t size, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Fill an MPI with a number of random bytes.
int mbedtls_mpi_gcd (mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B)
 Compute the greatest common divisor: G = gcd(A, B)
int mbedtls_mpi_inv_mod (mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *N)
 Compute the modular inverse: X = A^-1 mod N.
MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime (const mbedtls_mpi *X, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Perform a Miller-Rabin primality test with error probability of 2-80.
int mbedtls_mpi_is_prime_ext (const mbedtls_mpi *X, int rounds, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Miller-Rabin primality test.
int mbedtls_mpi_gen_prime (mbedtls_mpi *X, size_t nbits, int flags, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Generate a prime number.
int mbedtls_mpi_self_test (int verbose)
 Checkup routine.

Detailed Description

Multi-precision integer library.

Definition in file bignum.h.


Typedef Documentation

typedef struct mbedtls_mpi mbedtls_mpi

MPI structure.


Enumeration Type Documentation

Flags for mbedtls_mpi_gen_prime()

Each of these flags is a constraint on the result X returned by mbedtls_mpi_gen_prime().

Enumerator:
MBEDTLS_MPI_GEN_PRIME_FLAG_DH 

(X-1)/2 is prime too

MBEDTLS_MPI_GEN_PRIME_FLAG_LOW_ERR 

lower error rate from 2-80 to 2-128

Definition at line 958 of file bignum.h.


Function Documentation

int mbedtls_mpi_add_abs ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform an unsigned addition of MPIs: X = |A| + |B|.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe first summand. This must point to an initialized MPI.
BThe second summand. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1171 of file bignum.c.

int mbedtls_mpi_add_int ( mbedtls_mpi X,
const mbedtls_mpi A,
mbedtls_mpi_sint  b 
)

Perform a signed addition of an MPI and an integer: X = A + b.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe first summand. This must point to an initialized MPI.
bThe second summand.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1367 of file bignum.c.

int mbedtls_mpi_add_mpi ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform a signed addition of MPIs: X = A + B.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe first summand. This must point to an initialized MPI.
BThe second summand. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1297 of file bignum.c.

size_t mbedtls_mpi_bitlen ( const mbedtls_mpi X )

Return the number of bits up to and including the most significant bit of value 1.

*

Note:
This is same as the one-based index of the most significant bit of value 1.
Parameters:
XThe MPI to query. This must point to an initialized MPI.
Returns:
The number of bits up to and including the most significant bit of value 1.

Definition at line 414 of file bignum.c.

int mbedtls_mpi_cmp_abs ( const mbedtls_mpi X,
const mbedtls_mpi Y 
)

Compare the absolute values of two MPIs.

Parameters:
XThe left-hand MPI. This must point to an initialized MPI.
YThe right-hand MPI. This must point to an initialized MPI.
Returns:
1 if `|X|` is greater than `|Y|`.
-1 if `|X|` is lesser than `|Y|`.
0 if `|X|` is equal to `|Y|`.

Definition at line 1087 of file bignum.c.

int mbedtls_mpi_cmp_int ( const mbedtls_mpi X,
mbedtls_mpi_sint  z 
)

Compare an MPI with an integer.

Parameters:
XThe left-hand MPI. This must point to an initialized MPI.
zThe integer value to compare X to.
Returns:
1 if X is greater than z.
-1 if X is lesser than z.
0 if X is equal to z.

Definition at line 1154 of file bignum.c.

int mbedtls_mpi_cmp_mpi ( const mbedtls_mpi X,
const mbedtls_mpi Y 
)

Compare two MPIs.

Parameters:
XThe left-hand MPI. This must point to an initialized MPI.
YThe right-hand MPI. This must point to an initialized MPI.
Returns:
1 if X is greater than Y.
-1 if X is lesser than Y.
0 if X is equal to Y.

Definition at line 1119 of file bignum.c.

int mbedtls_mpi_copy ( mbedtls_mpi X,
const mbedtls_mpi Y 
)

Make a copy of an MPI.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
YThe source MPI. This must point to an initialized MPI.
Note:
The limb-buffer in the destination MPI is enlarged if necessary to hold the value in the source MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 191 of file bignum.c.

int mbedtls_mpi_div_int ( mbedtls_mpi Q,
mbedtls_mpi R,
const mbedtls_mpi A,
mbedtls_mpi_sint  b 
)

Perform a division with remainder of an MPI by an integer: A = Q * b + R.

Parameters:
QThe destination MPI for the quotient. This may be NULL if the value of the quotient is not needed.
RThe destination MPI for the remainder value. This may be NULL if the value of the remainder is not needed.
AThe dividend. This must point to an initialized MPi.
bThe divisor.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b equals zero.
Another negative error code on different kinds of failure.

Definition at line 1747 of file bignum.c.

int mbedtls_mpi_div_mpi ( mbedtls_mpi Q,
mbedtls_mpi R,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform a division with remainder of two MPIs: A = Q * B + R.

Parameters:
QThe destination MPI for the quotient. This may be NULL if the value of the quotient is not needed.
RThe destination MPI for the remainder value. This may be NULL if the value of the remainder is not needed.
AThe dividend. This must point to an initialized MPi.
BThe divisor. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B equals zero.
Another negative error code on different kinds of failure.

Definition at line 1629 of file bignum.c.

int mbedtls_mpi_exp_mod ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi E,
const mbedtls_mpi N,
mbedtls_mpi _RR 
)

Perform a sliding-window exponentiation: X = A^E mod N.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe base of the exponentiation. This must point to an initialized MPI.
EThe exponent MPI. This must point to an initialized MPI.
NThe base for the modular reduction. This must point to an initialized MPI.
_RRA helper MPI depending solely on N which can be used to speed-up multiple modular exponentiations for the same value of N. This may be NULL. If it is not NULL, it must point to an initialized MPI. If it hasn't been used after the call to mbedtls_mpi_init(), this function will compute the helper value and store it in _RR for reuse on subsequent calls to this function. Otherwise, the function will assume that _RR holds the helper value set by a previous call to mbedtls_mpi_exp_mod(), and reuse it.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is negative or even, or if E is negative.
Another negative error code on different kinds of failures.

Definition at line 1926 of file bignum.c.

int mbedtls_mpi_fill_random ( mbedtls_mpi X,
size_t  size,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Fill an MPI with a number of random bytes.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
sizeThe number of random bytes to generate.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe 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_ALLOC_FAILED if a memory allocation failed.
Another negative error code on 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.

Definition at line 2203 of file bignum.c.

void mbedtls_mpi_free ( mbedtls_mpi X )

This function frees the components of an MPI context.

Parameters:
XThe MPI context to be cleared. This may be NULL, in which case this function is a no-op. If it is not NULL, it must point to an initialized MPI.

Definition at line 101 of file bignum.c.

int mbedtls_mpi_gcd ( mbedtls_mpi G,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Compute the greatest common divisor: G = gcd(A, B)

Parameters:
GThe destination MPI. This must point to an initialized MPI.
AThe first operand. This must point to an initialized MPI.
BThe second operand. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 2143 of file bignum.c.

int mbedtls_mpi_gen_prime ( mbedtls_mpi X,
size_t  nbits,
int  flags,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Generate a prime number.

Parameters:
XThe destination MPI to store the generated prime in. This must point to an initialized MPi.
nbitsThe required size of the destination MPI in bits. This must be between 3 and MBEDTLS_MPI_MAX_BITS.
flagsA mask of flags of type mbedtls_mpi_gen_prime_flag_t.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG parameter to be passed to f_rng. This may be NULL if f_rng doesn't use a context parameter.
Returns:
0 if successful, in which case X holds a probably prime number.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between 3 and MBEDTLS_MPI_MAX_BITS.

Definition at line 2545 of file bignum.c.

int mbedtls_mpi_get_bit ( const mbedtls_mpi X,
size_t  pos 
)

Get a specific bit from an MPI.

Parameters:
XThe MPI to query. This must be initialized.
posZero-based index of the bit to query.
Returns:
0 or 1 on success, depending on whether bit pos of X is unset or set.
A negative error code on failure.

Definition at line 334 of file bignum.c.

int mbedtls_mpi_grow ( mbedtls_mpi X,
size_t  nblimbs 
)

Enlarge an MPI to the specified number of limbs.

Note:
This function does nothing if the MPI is already large enough.
Parameters:
XThe MPI to grow. It must be initialized.
nblimbsThe target number of limbs.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 120 of file bignum.c.

void mbedtls_mpi_init ( mbedtls_mpi X )

Initialize an MPI context.

This makes the MPI ready to be set or freed, but does not define a value for the MPI.

Parameters:
XThe MPI context to initialize. This must not be NULL.

Definition at line 89 of file bignum.c.

int mbedtls_mpi_inv_mod ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi N 
)

Compute the modular inverse: X = A^-1 mod N.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe MPI to calculate the modular inverse of. This must point to an initialized MPI.
NThe base of the modular inversion. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is less than or equal to one.
MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if has no modular inverse with respect to N.

Definition at line 2236 of file bignum.c.

MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime ( const mbedtls_mpi X,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Perform a Miller-Rabin primality test with error probability of 2-80.

Parameters:
XThe MPI to check for primality. This must point to an initialized MPI.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG parameter to be passed to f_rng. This may be NULL if f_rng doesn't use a context parameter.
Returns:
0 if successful, i.e. X is probably prime.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime.
Another negative error code on other kinds of failure.

Definition at line 2522 of file bignum.c.

int mbedtls_mpi_is_prime_ext ( const mbedtls_mpi X,
int  rounds,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Miller-Rabin primality test.

Warning:
If X is potentially generated by an adversary, for example when validating cryptographic parameters that you didn't generate yourself and that are supposed to be prime, then rounds should be at least the half of the security strength of the cryptographic algorithm. On the other hand, if X is chosen uniformly or non-adversially (as is the case when mbedtls_mpi_gen_prime calls this function), then rounds can be much lower.
Parameters:
XThe MPI to check for primality. This must point to an initialized MPI.
roundsThe number of bases to perform the Miller-Rabin primality test for. The probability of returning 0 on a composite is at most 2-2*rounds.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG parameter to be passed to f_rng. This may be NULL if f_rng doesn't use a context parameter.
Returns:
0 if successful, i.e. X is probably prime.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime.
Another negative error code on other kinds of failure.

Definition at line 2487 of file bignum.c.

size_t mbedtls_mpi_lsb ( const mbedtls_mpi X )

Return the number of bits of value 0 before the least significant bit of value 1.

Note:
This is the same as the zero-based index of the least significant bit of value 1.
Parameters:
XThe MPI to query.
Returns:
The number of bits of value 0 before the least significant bit of value 1 in X.

Definition at line 380 of file bignum.c.

int mbedtls_mpi_lset ( mbedtls_mpi X,
mbedtls_mpi_sint  z 
)

Store integer value in MPI.

Parameters:
XThe MPI to set. This must be initialized.
zThe value to use.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 315 of file bignum.c.

int mbedtls_mpi_mod_int ( mbedtls_mpi_uint *  r,
const mbedtls_mpi A,
mbedtls_mpi_sint  b 
)

Perform a modular reduction with respect to an integer.

r = A mod b

Parameters:
rThe address at which to store the residue. This must not be NULL.
AThe MPI to compute the residue of. This must point to an initialized MPi.
bThe integer base of the modular reduction.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b equals zero.
MBEDTLS_ERR_MPI_NEGATIVE_VALUE if b is negative.
Another negative error code on different kinds of failure.

Definition at line 1792 of file bignum.c.

int mbedtls_mpi_mod_mpi ( mbedtls_mpi R,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform a modular reduction.

R = A mod B

Parameters:
RThe destination MPI for the residue value. This must point to an initialized MPI.
AThe MPI to compute the residue of. This must point to an initialized MPI.
BThe base of the modular reduction. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B equals zero.
MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B is negative.
Another negative error code on different kinds of failure.

Definition at line 1766 of file bignum.c.

int mbedtls_mpi_mul_int ( mbedtls_mpi X,
const mbedtls_mpi A,
mbedtls_mpi_uint  b 
)

Perform a multiplication of an MPI with an unsigned integer: X = A * b.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe first factor. This must point to an initialized MPI.
bThe second factor.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1515 of file bignum.c.

int mbedtls_mpi_mul_mpi ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform a multiplication of two MPIs: X = A * B.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe first factor. This must point to an initialized MPI.
BThe second factor. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1475 of file bignum.c.

int mbedtls_mpi_read_binary ( mbedtls_mpi X,
const unsigned char *  buf,
size_t  buflen 
)

Import an MPI from unsigned big endian binary data.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
bufThe input buffer. This must be a readable buffer of length buflen Bytes.
buflenThe length of the input buffer p in Bytes.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 865 of file bignum.c.

int mbedtls_mpi_read_binary_le ( mbedtls_mpi X,
const unsigned char *  buf,
size_t  buflen 
)

Import X from unsigned binary data, little endian.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
bufThe input buffer. This must be a readable buffer of length buflen Bytes.
buflenThe length of the input buffer p in Bytes.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 832 of file bignum.c.

int mbedtls_mpi_read_file ( mbedtls_mpi X,
int  radix,
FILE *  fin 
)

Read an MPI from a line in an opened file.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
radixThe numeric base of the string representation used in the source line.
finThe input file handle to use. This must not be NULL.
Note:
On success, this function advances the file stream to the end of the current line or to EOF.

The function returns 0 on an empty line.

Leading whitespaces are ignored, as is a '0x' prefix for radix 16.

Returns:
0 if successful.
MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer is too small.
Another negative error code on failure.

Definition at line 659 of file bignum.c.

int mbedtls_mpi_read_string ( mbedtls_mpi X,
int  radix,
const char *  s 
)

Import an MPI from an ASCII string.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
radixThe numeric base of the input string.
sNull-terminated string buffer.
Returns:
0 if successful.
A negative error code on failure.

Definition at line 458 of file bignum.c.

int mbedtls_mpi_safe_cond_assign ( mbedtls_mpi X,
const mbedtls_mpi Y,
unsigned char  assign 
)

Perform a safe conditional copy of MPI which doesn't reveal whether the condition was true or not.

Parameters:
XThe MPI to conditionally assign to. This must point to an initialized MPI.
YThe MPI to be assigned from. This must point to an initialized MPI.
assignThe condition deciding whether to perform the assignment or not. Possible values: * 1: Perform the assignment `X = Y`. * 0: Keep the original value of X.
Note:
This function is equivalent to `if( assign ) mbedtls_mpi_copy( X, Y );` except that it avoids leaking any information about whether the assignment was done or not (the above code may leak information through branch prediction and/or memory access patterns analysis).
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 249 of file bignum.c.

int mbedtls_mpi_safe_cond_swap ( mbedtls_mpi X,
mbedtls_mpi Y,
unsigned char  assign 
)

Perform a safe conditional swap which doesn't reveal whether the condition was true or not.

Parameters:
XThe first MPI. This must be initialized.
YThe second MPI. This must be initialized.
assignThe condition deciding whether to perform the swap or not. Possible values: * 1: Swap the values of X and Y. * 0: Keep the original values of X and Y.
Note:
This function is equivalent to if( assign ) mbedtls_mpi_swap( X, Y ); except that it avoids leaking any information about whether the assignment was done or not (the above code may leak information through branch prediction and/or memory access patterns analysis).
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 279 of file bignum.c.

int mbedtls_mpi_self_test ( int  verbose )

Checkup routine.

Returns:
0 if successful, or 1 if the test failed

Definition at line 2681 of file bignum.c.

int mbedtls_mpi_set_bit ( mbedtls_mpi X,
size_t  pos,
unsigned char  val 
)

Modify a specific bit in an MPI.

Note:
This function will grow the target MPI if necessary to set a bit to 1 in a not yet existing limb. It will not grow if the bit should be set to 0.
Parameters:
XThe MPI to modify. This must be initialized.
posZero-based index of the bit to modify.
valThe desired value of bit pos: 0 or 1.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Another negative error code on other kinds of failure.

Definition at line 351 of file bignum.c.

int mbedtls_mpi_shift_l ( mbedtls_mpi X,
size_t  count 
)

Perform a left-shift on an MPI: X <<= count.

Parameters:
XThe MPI to shift. This must point to an initialized MPI.
countThe number of bits to shift by.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 992 of file bignum.c.

int mbedtls_mpi_shift_r ( mbedtls_mpi X,
size_t  count 
)

Perform a right-shift on an MPI: X >>= count.

Parameters:
XThe MPI to shift. This must point to an initialized MPI.
countThe number of bits to shift by.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1043 of file bignum.c.

int mbedtls_mpi_shrink ( mbedtls_mpi X,
size_t  nblimbs 
)

This function resizes an MPI downwards, keeping at least the specified number of limbs.

If X is smaller than nblimbs, it is resized up instead.

Parameters:
XThe MPI to shrink. This must point to an initialized MPI.
nblimbsThe minimum number of limbs to keep.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed (this can only happen when resizing up).
Another negative error code on other kinds of failure.

Definition at line 151 of file bignum.c.

size_t mbedtls_mpi_size ( const mbedtls_mpi X )

Return the total size of an MPI value in bytes.

Parameters:
XThe MPI to use. This must point to an initialized MPI.
Note:
The value returned by this function may be less than the number of bytes used to store X internally. This happens if and only if there are trailing bytes of value zero.
Returns:
The least number of bytes capable of storing the absolute value of X.

Definition at line 433 of file bignum.c.

int mbedtls_mpi_sub_abs ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform an unsigned subtraction of MPIs: X = |A| - |B|.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe minuend. This must point to an initialized MPI.
BThe subtrahend. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B is greater than A.
Another negative error code on different kinds of failure.

Definition at line 1251 of file bignum.c.

int mbedtls_mpi_sub_int ( mbedtls_mpi X,
const mbedtls_mpi A,
mbedtls_mpi_sint  b 
)

Perform a signed subtraction of an MPI and an integer: X = A - b.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe minuend. This must point to an initialized MPI.
bThe subtrahend.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1385 of file bignum.c.

int mbedtls_mpi_sub_mpi ( mbedtls_mpi X,
const mbedtls_mpi A,
const mbedtls_mpi B 
)

Perform a signed subtraction of MPIs: X = A - B.

Parameters:
XThe destination MPI. This must point to an initialized MPI.
AThe minuend. This must point to an initialized MPI.
BThe subtrahend. This must point to an initialized MPI.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
Another negative error code on different kinds of failure.

Definition at line 1332 of file bignum.c.

void mbedtls_mpi_swap ( mbedtls_mpi X,
mbedtls_mpi Y 
)

Swap the contents of two MPIs.

Parameters:
XThe first MPI. It must be initialized.
YThe second MPI. It must be initialized.

Definition at line 233 of file bignum.c.

int mbedtls_mpi_write_binary ( const mbedtls_mpi X,
unsigned char *  buf,
size_t  buflen 
)

Export X into unsigned binary data, big endian.

Always fills the whole buffer, which will start with zeros if the number is smaller.

Parameters:
XThe source MPI. This must point to an initialized MPI.
bufThe output buffer. This must be a writable buffer of length buflen Bytes.
buflenThe size of the output buffer buf in Bytes.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if buf isn't large enough to hold the value of X.
Another negative error code on different kinds of failure.

Definition at line 946 of file bignum.c.

int mbedtls_mpi_write_binary_le ( const mbedtls_mpi X,
unsigned char *  buf,
size_t  buflen 
)

Export X into unsigned binary data, little endian.

Always fills the whole buffer, which will end with zeros if the number is smaller.

Parameters:
XThe source MPI. This must point to an initialized MPI.
bufThe output buffer. This must be a writable buffer of length buflen Bytes.
buflenThe size of the output buffer buf in Bytes.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if buf isn't large enough to hold the value of X.
Another negative error code on different kinds of failure.

Definition at line 907 of file bignum.c.

int mbedtls_mpi_write_file ( const char *  p,
const mbedtls_mpi X,
int  radix,
FILE *  fout 
)

Export an MPI into an opened file.

Parameters:
pA string prefix to emit prior to the MPI data. For example, this might be a label, or "0x" when printing in base 16. This may be NULL if no prefix is needed.
XThe source MPI. This must point to an initialized MPI.
radixThe numeric base to be used in the emitted string.
foutThe output file handle. This may be NULL, in which case the output is written to stdout.
Returns:
0 if successful.
A negative error code on failure.

Definition at line 698 of file bignum.c.

int mbedtls_mpi_write_string ( const mbedtls_mpi X,
int  radix,
char *  buf,
size_t  buflen,
size_t *  olen 
)

Export an MPI to an ASCII string.

Parameters:
XThe source MPI. This must point to an initialized MPI.
radixThe numeric base of the output string.
bufThe buffer to write the string to. This must be writable buffer of length buflen Bytes.
buflenThe available size in Bytes of buf.
olenThe address at which to store the length of the string written, including the final NULL byte. This must not be NULL.
Note:
You can call this function with `buflen == 0` to obtain the minimum required buffer size in `*olen`.
Returns:
0 if successful.
MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer buf is too small to hold the value of X in the desired base. In this case, `*olen` is nonetheless updated to contain the size of buf required for a successful call.
Another negative error code on different kinds of failure.

Definition at line 571 of file bignum.c.