12.3 MPI formats

The following functions are used to convert between an external representation of an MPI and the internal one of Libgcrypt.

Function: gcry_error_t gcry_mpi_scan (gcry_mpi_t *r_mpi, enum gcry_mpi_format format, const unsigned char *buffer, size_t buflen, size_t *nscanned)

Convert the external representation of an integer stored in buffer with a length of buflen into a newly created MPI returned which will be stored at the address of r_mpi. For certain formats the length argument is not required and should be passed as 0. A buflen larger than 16 MiB will be rejected. After a successful operation the variable nscanned receives the number of bytes actually scanned unless nscanned was given as NULL. format describes the format of the MPI as stored in buffer:

GCRYMPI_FMT_STD

2-complement stored without a length header. Note that gcry_mpi_print stores a 0 as a string of zero length.

GCRYMPI_FMT_PGP

As used by OpenPGP (only defined as unsigned). This is basically GCRYMPI_FMT_STD with a 2 byte big endian length header. A length header indicating a length of more than 16384 is not allowed.

GCRYMPI_FMT_SSH

As used in the Secure Shell protocol. This is GCRYMPI_FMT_STD with a 4 byte big endian header.

GCRYMPI_FMT_HEX

Stored as a string with each byte of the MPI encoded as 2 hex digits. Negative numbers are prefixed with a minus sign and in addition the high bit is always zero to make clear that an explicit sign ist used. When using this format, buflen must be zero.

GCRYMPI_FMT_USG

Simple unsigned integer.

Note that all of the above formats store the integer in big-endian format (MSB first). Leading zeroes are stripped unless they are required to keep a value positive.

Function: gcry_error_t gcry_mpi_print (enum gcry_mpi_format format, unsigned char *buffer, size_t buflen, size_t *nwritten, const gcry_mpi_t a)

Convert the MPI a into an external representation described by format (see above) and store it in the provided buffer which has a usable length of at least buflen bytes. If nwritten is not NULL, it will receive the number of bytes actually stored in buffer after a successful operation.

Function: gcry_error_t gcry_mpi_aprint (enum gcry_mpi_format format, unsigned char **buffer, size_t *nbytes, const gcry_mpi_t a)

Convert the MPI a into an external representation described by format (see above) and store it in a newly allocated buffer which address will be stored in the variable buffer points to. The number of bytes stored in this buffer will be stored in the variable nbytes points to, unless nbytes is NULL.

Even if nbytes is zero, the function allocates at least one byte and store a zero there. Thus with formats GCRYMPI_FMT_STD and GCRYMPI_FMT_USG the caller may safely set a returned length of 0 to 1 to represent a zero as a 1 byte string.

Function: void gcry_mpi_dump (const gcry_mpi_t a)

Dump the value of a in a format suitable for debugging to Libgcrypt’s logging stream. Note that one leading space but no trailing space or linefeed will be printed. It is okay to pass NULL for a.