12.8 Miscellaneous

An MPI data type is allowed to be “misused” to store an arbitrary value. Two functions implement this kludge:

Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t a, void *p, unsigned int nbits)

Store nbits of the value p points to in a and mark a as an opaque value (i.e. an value that can’t be used for any math calculation and is only used to store an arbitrary bit pattern in a). Ownership of p is taken by this function and thus the user may not dereference the passed value anymore. It is required that the memory referenced by p has been allocated in a way that gcry_free is able to release it.

WARNING: Never use an opaque MPI for actual math operations. The only valid functions are gcry_mpi_get_opaque and gcry_mpi_release. Use gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.

Function: gcry_mpi_t gcry_mpi_set_opaque_copy (gcry_mpi_t a, const void *p, unsigned int nbits)

Same as gcry_mpi_set_opaque but ownership of p is not taken; instead a copy of p is used.

Function: void * gcry_mpi_get_opaque (gcry_mpi_t a, unsigned int *nbits)

Return a pointer to an opaque value stored in a and return its size in nbits. Note that the returned pointer is still owned by a and that the function should never be used for an non-opaque MPI.

Each MPI has an associated set of flags for special purposes. The currently defined flags are:

GCRYMPI_FLAG_SECURE

Setting this flag converts a into an MPI stored in "secure memory". Clearing this flag is not allowed.

GCRYMPI_FLAG_OPAQUE

This is an internal flag, indicating that an opaque value and not an integer is stored. This is an read-only flag; it may not be set or cleared.

GCRYMPI_FLAG_IMMUTABLE

If this flag is set, the MPI is marked as immutable. Setting or changing the value of that MPI is ignored and an error message is logged. The flag is sometimes useful for debugging.

GCRYMPI_FLAG_CONST

If this flag is set, the MPI is marked as a constant and as immutable Setting or changing the value of that MPI is ignored and an error message is logged. Such an MPI will never be deallocated and may thus be used without copying. Note that using gcry_mpi_copy will return a copy of that constant with this and the immutable flag cleared. A few commonly used constants are pre-defined and accessible using the macros GCRYMPI_CONST_ONE, GCRYMPI_CONST_TWO, GCRYMPI_CONST_THREE, GCRYMPI_CONST_FOUR, and GCRYMPI_CONST_EIGHT.

GCRYMPI_FLAG_USER1

GCRYMPI_FLAG_USER2

GCRYMPI_FLAG_USER3

GCRYMPI_FLAG_USER4

These flags are reserved for use by the application.

Function: void gcry_mpi_set_flag (gcry_mpi_t a, enum gcry_mpi_flag flag)

Set the flag for the MPI a. The only allowed flags are GCRYMPI_FLAG_SECURE, GCRYMPI_FLAG_IMMUTABLE, and GCRYMPI_FLAG_CONST.

Function: void gcry_mpi_clear_flag (gcry_mpi_t a, enum gcry_mpi_flag flag)

Clear flag for the multi-precision-integers a. The only allowed flag is GCRYMPI_FLAG_IMMUTABLE but only if GCRYMPI_FLAG_CONST is not set. If GCRYMPI_FLAG_CONST is set, clearing GCRYMPI_FLAG_IMMUTABLE will simply be ignored.

Function: int gcry_mpi_get_flag (gcry_mpi_t a, enum gcry_mpi_flag flag)

Return true if flag is set for a.

To put a random value into an MPI, the following convenience function may be used:

Function: void gcry_mpi_randomize (gcry_mpi_t w, unsigned int nbits, enum gcry_random_level level)

Set the multi-precision-integers w to a random non-negative number of nbits, using random data quality of level level. In case nbits is not a multiple of a byte, nbits is rounded up to the next byte boundary. When using a level of GCRY_WEAK_RANDOM, this function makes use of gcry_create_nonce.