12.2 Basic functions

To work with MPIs, storage must be allocated and released for the numbers. This can be done with one of these functions:

Function: gcry_mpi_t gcry_mpi_new (unsigned int nbits)

Allocate a new MPI object, initialize it to 0 and initially allocate enough memory for a number of at least nbits. This pre-allocation is only a small performance issue and not actually necessary because Libgcrypt automatically re-allocates the required memory.

Function: gcry_mpi_t gcry_mpi_snew (unsigned int nbits)

This is identical to gcry_mpi_new but allocates the MPI in the so called "secure memory" which in turn will take care that all derived values will also be stored in this "secure memory". Use this for highly confidential data like private key parameters.

Function: gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t a)

Create a new MPI as the exact copy of a but with the constant and immutable flags cleared.

Function: void gcry_mpi_release (gcry_mpi_t a)

Release the MPI a and free all associated resources. Passing NULL is allowed and ignored. When a MPI stored in the "secure memory" is released, that memory gets wiped out immediately.

The simplest operations are used to assign a new value to an MPI:

Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t w, const gcry_mpi_t u)

Assign the value of u to w and return w. If NULL is passed for w, a new MPI is allocated, set to the value of u and returned.

Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t w, unsigned long u)

Assign the value of u to w and return w. If NULL is passed for w, a new MPI is allocated, set to the value of u and returned. This function takes an unsigned int as type for u and thus it is only possible to set w to small values (usually up to the word size of the CPU).

Function: gcry_error_t gcry_mpi_get_ui (unsigned int *w, gcry_mpi_t u)

If u is not negative and small enough to be stored in an unsigned int variable, store its value at w. If the value does not fit or is negative, return GPG_ERR_ERANGE and do not change the value stored at w. Note that this function returns an unsigned int so that this value can immediately be used with the bit test functions. This is in contrast to the other "_ui" functions which allow for values up to an unsigned long.

Function: void gcry_mpi_swap (gcry_mpi_t a, gcry_mpi_t b)

Swap the values of a and b.

Function: void gcry_mpi_snatch (gcry_mpi_t w, const gcry_mpi_t u)

Set u into w and release u. If w is NULL, only u will be released.

Function: void gcry_mpi_neg (gcry_mpi_t w, gcry_mpi_t u)

Set the sign of w to the negative of u.

Function: void gcry_mpi_abs (gcry_mpi_t w)

Clear the sign of w.