mbed TLS v2.23.0: bignum.h File Reference

mbed TLS v2.23.0

Data Structures | Macros | Typedefs | Enumerations | Functions
bignum.h File Reference

Multi-precision integer library. More...

`#include "mbedtls/config.h"`
`#include <stddef.h>`
`#include <stdint.h>`
`#include <stdio.h>`
Include dependency graph for bignum.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | mbedtls_mpi
| MPI structure. More...

## Macros
#define | MBEDTLS_ERR_MPI_FILE_IO_ERROR -0x0002
#define | MBEDTLS_ERR_MPI_BAD_INPUT_DATA -0x0004
#define | MBEDTLS_ERR_MPI_INVALID_CHARACTER -0x0006
#define | MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL -0x0008
#define | MBEDTLS_ERR_MPI_NEGATIVE_VALUE -0x000A
#define | MBEDTLS_ERR_MPI_DIVISION_BY_ZERO -0x000C
#define | MBEDTLS_ERR_MPI_NOT_ACCEPTABLE -0x000E
#define | MBEDTLS_ERR_MPI_ALLOC_FAILED -0x0010
#define | MBEDTLS_MPI_CHK(f)
#define | MBEDTLS_MPI_MAX_LIMBS 10000
#define | MBEDTLS_MPI_WINDOW_SIZE 6
#define | MBEDTLS_MPI_MAX_SIZE 1024
#define | MBEDTLS_MPI_MAX_BITS ( 8 * MBEDTLS_MPI_MAX_SIZE )
#define | MBEDTLS_MPI_MAX_BITS_SCALE100 ( 100 * MBEDTLS_MPI_MAX_BITS )
#define | MBEDTLS_LN_2_DIV_LN_10_SCALE100 332
#define | MBEDTLS_MPI_RW_BUFFER_SIZE ( ((MBEDTLS_MPI_MAX_BITS_SCALE100 + MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6 )
#define | MBEDTLS_HAVE_INT32
#define | MBEDTLS_HAVE_UDBL
#define | MBEDTLS_DEPRECATED

## Typedefs
typedef int32_t | mbedtls_mpi_sint
typedef uint32_t | mbedtls_mpi_uint
typedef uint64_t | mbedtls_t_udbl
typedef struct mbedtls_mpi | mbedtls_mpi
| MPI structure. More...

## 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. More...
void | mbedtls_mpi_free (mbedtls_mpi *X)
| This function frees the components of an MPI context. More...
int | mbedtls_mpi_grow (mbedtls_mpi *X, size_t nblimbs)
| Enlarge an MPI to the specified number of limbs. More...
int | mbedtls_mpi_shrink (mbedtls_mpi *X, size_t nblimbs)
| This function resizes an MPI downwards, keeping at least the specified number of limbs. More...
int | mbedtls_mpi_copy (mbedtls_mpi *X, const mbedtls_mpi *Y)
| Make a copy of an MPI. More...
void | mbedtls_mpi_swap (mbedtls_mpi *X, mbedtls_mpi *Y)
| Swap the contents of two MPIs. More...
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. More...
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. More...
int | mbedtls_mpi_lset (mbedtls_mpi *X, mbedtls_mpi_sint z)
| Store integer value in MPI. More...
int | mbedtls_mpi_get_bit (const mbedtls_mpi *X, size_t pos)
| Get a specific bit from an MPI. More...
int | mbedtls_mpi_set_bit (mbedtls_mpi *X, size_t pos, unsigned char val)
| Modify a specific bit in an MPI. More...
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`. More...
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`. More...
size_t | mbedtls_mpi_size (const mbedtls_mpi *X)
| Return the total size of an MPI value in bytes. More...
int | mbedtls_mpi_read_string (mbedtls_mpi *X, int radix, const char *s)
| Import an MPI from an ASCII string. More...
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. More...
int | mbedtls_mpi_read_file (mbedtls_mpi *X, int radix, FILE *fin)
| Read an MPI from a line in an opened file. More...
int | mbedtls_mpi_write_file (const char *p, const mbedtls_mpi *X, int radix, FILE *fout)
| Export an MPI into an opened file. More...
int | mbedtls_mpi_read_binary (mbedtls_mpi *X, const unsigned char *buf, size_t buflen)
| Import an MPI from unsigned big endian binary data. More...
int | mbedtls_mpi_read_binary_le (mbedtls_mpi *X, const unsigned char *buf, size_t buflen)
| Import X from unsigned binary data, little endian. More...
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. More...
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. More...
int | mbedtls_mpi_shift_l (mbedtls_mpi *X, size_t count)
| Perform a left-shift on an MPI: X <<= count. More...
int | mbedtls_mpi_shift_r (mbedtls_mpi *X, size_t count)
| Perform a right-shift on an MPI: X >>= count. More...
int | mbedtls_mpi_cmp_abs (const mbedtls_mpi *X, const mbedtls_mpi *Y)
| Compare the absolute values of two MPIs. More...
int | mbedtls_mpi_cmp_mpi (const mbedtls_mpi *X, const mbedtls_mpi *Y)
| Compare two MPIs. More...
int | mbedtls_mpi_lt_mpi_ct (const mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned *ret)
| Check if an MPI is less than the other in constant time. More...
int | mbedtls_mpi_cmp_int (const mbedtls_mpi *X, mbedtls_mpi_sint z)
| Compare an MPI with an integer. More...
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|. More...
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|. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
int | mbedtls_mpi_mod_mpi (mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B)
| Perform a modular reduction. R = A mod B. More...
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. More...
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. More...
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. More...
int | mbedtls_mpi_gcd (mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B)
| Compute the greatest common divisor: G = gcd(A, B) More...
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. More...
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. More...
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. More...
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. More...
int | mbedtls_mpi_self_test (int verbose)
| Checkup routine. More...

## Detailed Description

Multi-precision integer library.

Definition in file bignum.h.

## Macro Definition Documentation

## ◆ MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

Definition at line 914 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_ALLOC_FAILED

#define MBEDTLS_ERR_MPI_ALLOC_FAILED -0x0010

Memory allocation failed.

Definition at line 48 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_BAD_INPUT_DATA

#define MBEDTLS_ERR_MPI_BAD_INPUT_DATA -0x0004

Bad input parameters to function.

Definition at line 42 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL

#define MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL -0x0008

The buffer is too small to write to.

Definition at line 44 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_DIVISION_BY_ZERO

#define MBEDTLS_ERR_MPI_DIVISION_BY_ZERO -0x000C

The input argument for division is zero, which is not allowed.

Definition at line 46 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_FILE_IO_ERROR

#define MBEDTLS_ERR_MPI_FILE_IO_ERROR -0x0002

An error occurred while reading from or writing to a file.

Definition at line 41 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_INVALID_CHARACTER

#define MBEDTLS_ERR_MPI_INVALID_CHARACTER -0x0006

There is an invalid character in the digit string.

Definition at line 43 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_NEGATIVE_VALUE

#define MBEDTLS_ERR_MPI_NEGATIVE_VALUE -0x000A

The input arguments are negative or result in illegal output.

Definition at line 45 of file bignum.h.

## ◆ MBEDTLS_ERR_MPI_NOT_ACCEPTABLE

#define MBEDTLS_ERR_MPI_NOT_ACCEPTABLE -0x000E

The input arguments are not acceptable.

Definition at line 47 of file bignum.h.

## ◆ MBEDTLS_HAVE_INT32

#define MBEDTLS_HAVE_INT32

Definition at line 170 of file bignum.h.

## ◆ MBEDTLS_HAVE_UDBL

#define MBEDTLS_HAVE_UDBL

Definition at line 176 of file bignum.h.

## ◆ MBEDTLS_LN_2_DIV_LN_10_SCALE100

#define MBEDTLS_LN_2_DIV_LN_10_SCALE100 332

Definition at line 107 of file bignum.h.

## ◆ MBEDTLS_MPI_CHK

#define MBEDTLS_MPI_CHK | ( |  | f | ) |

Value:
do \
{ \
if( ( ret = (f) ) != 0 ) \
goto cleanup; \
} while( 0 )

Definition at line 50 of file bignum.h.

## ◆ MBEDTLS_MPI_MAX_BITS

#define MBEDTLS_MPI_MAX_BITS ( 8 * MBEDTLS_MPI_MAX_SIZE )

Maximum number of bits for usable MPIs.

Definition at line 86 of file bignum.h.

## ◆ MBEDTLS_MPI_MAX_BITS_SCALE100

#define MBEDTLS_MPI_MAX_BITS_SCALE100 ( 100 * MBEDTLS_MPI_MAX_BITS )

Definition at line 106 of file bignum.h.

## ◆ MBEDTLS_MPI_MAX_LIMBS

#define MBEDTLS_MPI_MAX_LIMBS 10000

Definition at line 60 of file bignum.h.

## ◆ MBEDTLS_MPI_MAX_SIZE

#define MBEDTLS_MPI_MAX_SIZE 1024

Maximum number of bytes for usable MPIs.

Definition at line 83 of file bignum.h.

## ◆ MBEDTLS_MPI_RW_BUFFER_SIZE

#define MBEDTLS_MPI_RW_BUFFER_SIZE ( ((MBEDTLS_MPI_MAX_BITS_SCALE100 + MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6 )

Definition at line 108 of file bignum.h.

## ◆ MBEDTLS_MPI_WINDOW_SIZE

#define MBEDTLS_MPI_WINDOW_SIZE 6

Maximum windows size used.

Definition at line 72 of file bignum.h.

## Typedef Documentation

## ◆ mbedtls_mpi

typedef struct mbedtls_mpi mbedtls_mpi

MPI structure.

## ◆ mbedtls_mpi_sint

typedef int32_t mbedtls_mpi_sint

Definition at line 171 of file bignum.h.

## ◆ mbedtls_mpi_uint

typedef uint32_t mbedtls_mpi_uint

Definition at line 172 of file bignum.h.

## ◆ mbedtls_t_udbl

typedef uint64_t mbedtls_t_udbl

Definition at line 174 of file bignum.h.

## Enumeration Type Documentation

## ◆ mbedtls_mpi_gen_prime_flag_t

enum mbedtls_mpi_gen_prime_flag_t

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 976 of file bignum.h.

## Function Documentation

## ◆ mbedtls_mpi_add_abs()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The first summand. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_add_int()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The first summand. This must point to an initialized MPI.
  b | The 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.

## ◆ mbedtls_mpi_add_mpi()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The first summand. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_bitlen()

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

    X | The 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`.

## ◆ mbedtls_mpi_cmp_abs()

int mbedtls_mpi_cmp_abs | ( | const mbedtls_mpi * | X,
|  | const mbedtls_mpi * | Y
| ) |  |

Compare the absolute values of two MPIs.

Parameters

  X | The left-hand MPI. This must point to an initialized MPI.
  Y | The 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|`.

## ◆ mbedtls_mpi_cmp_int()

int mbedtls_mpi_cmp_int | ( | const mbedtls_mpi * | X,
|  | mbedtls_mpi_sint | z
| ) |  |

Compare an MPI with an integer.

Parameters

  X | The left-hand MPI. This must point to an initialized MPI.
  z | The 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`.

## ◆ mbedtls_mpi_cmp_mpi()

int mbedtls_mpi_cmp_mpi | ( | const mbedtls_mpi * | X,
|  | const mbedtls_mpi * | Y
| ) |  |

Compare two MPIs.

Parameters

  X | The left-hand MPI. This must point to an initialized MPI.
  Y | The 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`.

## ◆ mbedtls_mpi_copy()

int mbedtls_mpi_copy | ( | mbedtls_mpi * | X,
|  | const mbedtls_mpi * | Y
| ) |  |

Make a copy of an MPI.

Parameters

  X | The destination MPI. This must point to an initialized MPI.
  Y | The 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.

## ◆ mbedtls_mpi_div_int()

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

  Q | The destination MPI for the quotient. This may be `NULL` if the value of the quotient is not needed.
  R | The destination MPI for the remainder value. This may be `NULL` if the value of the remainder is not needed.
  A | The dividend. This must point to an initialized MPi.
  b | The 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.

## ◆ mbedtls_mpi_div_mpi()

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

  Q | The destination MPI for the quotient. This may be `NULL` if the value of the quotient is not needed.
  R | The destination MPI for the remainder value. This may be `NULL` if the value of the remainder is not needed.
  A | The dividend. This must point to an initialized MPi.
  B | The 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.

## ◆ mbedtls_mpi_exp_mod()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The base of the exponentiation. This must point to an initialized MPI.
  E | The exponent MPI. This must point to an initialized MPI.
  N | The base for the modular reduction. This must point to an initialized MPI.
  _RR | A 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.

## ◆ mbedtls_mpi_fill_random()

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

  X | The destination MPI. This must point to an initialized MPI.
  size | 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_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.

## ◆ mbedtls_mpi_free()

void mbedtls_mpi_free | ( | mbedtls_mpi * | X | ) |

This function frees the components of an MPI context.

Parameters

  X | The 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.

## ◆ mbedtls_mpi_gcd()

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

  G | The destination MPI. This must point to an initialized MPI.
  A | The first operand. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_gen_prime()

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

  X | The destination MPI to store the generated prime in. This must point to an initialized MPi.
  nbits | The required size of the destination MPI in bits. This must be between `3` and MBEDTLS_MPI_MAX_BITS.
  flags | A mask of flags of type mbedtls_mpi_gen_prime_flag_t.
  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 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.

## ◆ mbedtls_mpi_get_bit()

int mbedtls_mpi_get_bit | ( | const mbedtls_mpi * | X,
|  | size_t | pos
| ) |  |

Get a specific bit from an MPI.

Parameters

  X | The MPI to query. This must be initialized.
  pos | Zero-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.

## ◆ mbedtls_mpi_grow()

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

  X | The MPI to grow. It must be initialized.
  nblimbs | The 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.

## ◆ mbedtls_mpi_init()

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

  X | The MPI context to initialize. This must not be `NULL`.

## ◆ mbedtls_mpi_inv_mod()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The MPI to calculate the modular inverse of. This must point to an initialized MPI.
  N | The 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`.

## ◆ mbedtls_mpi_is_prime()

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.

Deprecated:
  Superseded by mbedtls_mpi_is_prime_ext() which allows specifying the number of Miller-Rabin rounds.

Parameters

  X | The MPI to check for primality. This must point to an initialized MPI.
  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 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.

## ◆ mbedtls_mpi_is_prime_ext()

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

  X | The MPI to check for primality. This must point to an initialized MPI.
  rounds | The 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_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 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.

## ◆ mbedtls_mpi_lsb()

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

  X | The MPI to query.

Returns
  The number of bits of value `0` before the least significant bit of value `1` in `X`.

## ◆ mbedtls_mpi_lset()

int mbedtls_mpi_lset | ( | mbedtls_mpi * | X,
|  | mbedtls_mpi_sint | z
| ) |  |

Store integer value in MPI.

Parameters

  X | The MPI to set. This must be initialized.
  z | The 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.

## ◆ mbedtls_mpi_lt_mpi_ct()

int mbedtls_mpi_lt_mpi_ct | ( | const mbedtls_mpi * | X,
|  | const mbedtls_mpi * | Y,
|  | unsigned * | ret
| ) |  |

Check if an MPI is less than the other in constant time.

Parameters

  X | The left-hand MPI. This must point to an initialized MPI with the same allocated length as Y.
  Y | The right-hand MPI. This must point to an initialized MPI with the same allocated length as X.
  ret | The result of the comparison: `1` if `X` is less than `Y`. `0` if `X` is greater than or equal to `Y`.

Returns
  0 on success.
  MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the allocated length of the two input MPIs is not the same.

## ◆ mbedtls_mpi_mod_int()

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

  r | The address at which to store the residue. This must not be `NULL`.
  A | The MPI to compute the residue of. This must point to an initialized MPi.
  b | The 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.

## ◆ mbedtls_mpi_mod_mpi()

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

  R | The destination MPI for the residue value. This must point to an initialized MPI.
  A | The MPI to compute the residue of. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_mul_int()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The first factor. This must point to an initialized MPI.
  b | The 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.

## ◆ mbedtls_mpi_mul_mpi()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The first factor. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_read_binary()

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

  X | The destination MPI. This must point to an initialized MPI.
  buf | The input buffer. This must be a readable buffer of length `buflen` Bytes.
  buflen | The 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.

## ◆ mbedtls_mpi_read_binary_le()

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

  X | The destination MPI. This must point to an initialized MPI.
  buf | The input buffer. This must be a readable buffer of length `buflen` Bytes.
  buflen | The 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.

## ◆ mbedtls_mpi_read_file()

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

Read an MPI from a line in an opened file.

Parameters

  X | The destination MPI. This must point to an initialized MPI.
  radix | The numeric base of the string representation used in the source line.
  fin | The 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.

## ◆ mbedtls_mpi_read_string()

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

Import an MPI from an ASCII string.

Parameters

  X | The destination MPI. This must point to an initialized MPI.
  radix | The numeric base of the input string.
  s | Null-terminated string buffer.

Returns
  `0` if successful.
  A negative error code on failure.

## ◆ mbedtls_mpi_safe_cond_assign()

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

  X | The MPI to conditionally assign to. This must point to an initialized MPI.
  Y | The MPI to be assigned from. This must point to an initialized MPI.
  assign | The 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.

## ◆ mbedtls_mpi_safe_cond_swap()

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

  X | The first MPI. This must be initialized.
  Y | The second MPI. This must be initialized.
  assign | The 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.

## ◆ mbedtls_mpi_self_test()

int mbedtls_mpi_self_test | ( | int | verbose | ) |

Checkup routine.

Returns
  0 if successful, or 1 if the test failed

## ◆ mbedtls_mpi_set_bit()

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

  X | The MPI to modify. This must be initialized.
  pos | Zero-based index of the bit to modify.
  val | The 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.

## ◆ mbedtls_mpi_shift_l()

int mbedtls_mpi_shift_l | ( | mbedtls_mpi * | X,
|  | size_t | count
| ) |  |

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

Parameters

  X | The MPI to shift. This must point to an initialized MPI.
  count | The 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.

## ◆ mbedtls_mpi_shift_r()

int mbedtls_mpi_shift_r | ( | mbedtls_mpi * | X,
|  | size_t | count
| ) |  |

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

Parameters

  X | The MPI to shift. This must point to an initialized MPI.
  count | The 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.

## ◆ mbedtls_mpi_shrink()

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

  X | The MPI to shrink. This must point to an initialized MPI.
  nblimbs | The 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.

## ◆ mbedtls_mpi_size()

size_t mbedtls_mpi_size | ( | const mbedtls_mpi * | X | ) |

Return the total size of an MPI value in bytes.

Parameters

  X | The 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`.

## ◆ mbedtls_mpi_sub_abs()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The minuend. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_sub_int()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The minuend. This must point to an initialized MPI.
  b | The subtrahend.

Returns
  `0` if successful.
  MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
  Another negative error code on different kinds of failure.

## ◆ mbedtls_mpi_sub_mpi()

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

  X | The destination MPI. This must point to an initialized MPI.
  A | The minuend. This must point to an initialized MPI.
  B | The 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.

## ◆ mbedtls_mpi_swap()

void mbedtls_mpi_swap | ( | mbedtls_mpi * | X,
|  | mbedtls_mpi * | Y
| ) |  |

Swap the contents of two MPIs.

Parameters

  X | The first MPI. It must be initialized.
  Y | The second MPI. It must be initialized.

## ◆ mbedtls_mpi_write_binary()

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

  X | The source MPI. This must point to an initialized MPI.
  buf | The output buffer. This must be a writable buffer of length `buflen` Bytes.
  buflen | The 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.

## ◆ mbedtls_mpi_write_binary_le()

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

  X | The source MPI. This must point to an initialized MPI.
  buf | The output buffer. This must be a writable buffer of length `buflen` Bytes.
  buflen | The 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.

## ◆ mbedtls_mpi_write_file()

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

Export an MPI into an opened file.

Parameters

  p | A 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.
  X | The source MPI. This must point to an initialized MPI.
  radix | The numeric base to be used in the emitted string.
  fout | The 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.

## ◆ mbedtls_mpi_write_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.

Parameters

  X | The source MPI. This must point to an initialized MPI.
  radix | The numeric base of the output string.
  buf | The buffer to write the string to. This must be writable buffer of length `buflen` Bytes.
  buflen | The available size in Bytes of `buf`.
  olen | The 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.