Next: , Previous: Basic functions, Up: MPI library


11.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. 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.
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.
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 C style string with each byte of the MPI encoded as 2 hex digits. 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).

— 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 the 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.

— 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.