[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
11.1 Data types | MPI related data types. | |
11.2 Basic functions | First steps with MPI numbers. | |
11.3 MPI formats | External representation of MPIs. | |
11.4 Calculations | Performing MPI calculations. | |
11.5 Comparisons | How to compare MPI values. | |
11.6 Bit manipulations | How to access single bits of MPI values. | |
11.7 Misc | Misc, fixme. |
Public key cryptography is based on mathematics with large numbers. To implement the public key functions, a library for handling these large numbers is required. Because of the general usefulness of such a library, its interface is exposed by Libgcrypt. The implementation is based on an old release of GNU Multi-Precision Library (GMP) but in the meantime heavily modified and stripped down to what is required for cryptography. For a lot of CPUs, high performance assembler implementations of some very low level functions are used to gain much better performance than with the standard C implementation.
In the context of Libgcrypt and in most other applications, these large numbers are called MPIs (multi-precision-integers).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gcry_mpi_t
type represents an object to hold an MPI.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To work with MPIs, storage must be allocated and released for the numbers. This can be done with one of these functions:
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.
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.
Create a new MPI as the exact copy of 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:
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.
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).
Swap the values of a and b.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following functions are used to convert between an external representation of an MPI and the internal one of Libgcrypt.
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 may 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
GCRYMPI_FMT_PGP
GCRYMPI_FMT_STD
with a 2 byte big endian length header.
GCRYMPI_FMT_SSH
GCRYMPI_FMT_STD
with a 4 byte big endian header.
GCRYMPI_FMT_HEX
GCRYMPI_FMT_USG
Note, that all of the above formats store the integer in big-endian format (MSB first).
Convert the MPI a into an external representation described by format (see above) and store it in the provided buffer which which has a usable length of at least the buflen bytes. If nwritten is not NULL, it wilol receive the number of bytes actually stored in buffer after a successful operation.
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
.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Basic arithmetic operations:
.
. Note, that v is an unsigned integer.
.
.
. v is an unsigned integer.
.
.
. v is an unsigned integer.
.
.
, . q and r may be passed
as NULL
. round should be negative or 0.
.
.
Set g to the greatest common divisor of a and b. Return true if the g is 1.
Set x to the multiplicative inverse of . Return true if the inverse exists.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The next 2 functions are used to compare MPIs:
Compare the big integer number u and v returning 0 for equality, a positive value for u > v and a negative for u < v.
Compare the big integer number u with the unsigned integer v returning 0 for equality, a positive value for u > v and a negative for u < v.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are a couple of functions to get information on arbitrary bits in an MPI and to set or clear them:
Return the number of bits required to represent a.
Return true if bit number n (counting from 0) is set in a.
Set bit number n in a.
Clear bit number n in a.
Set bit number n in a and clear all bits greater than n.
Clear bit number n in a and all bits greater than n.
Shift the value of a by n bits to the right and store the result in x.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The remaining MPI functions take care of very special properties of the implementation:
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.
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.
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.
Set the flag for the MPI a. Currently only the flag
GCRYMPI_FLAG_SECURE
is allowed to convert a into an MPI
stored in "secure memory".
Clear flag for the big integer a. Note, that this function is currently useless as no flags are allowed.
Return true when the flag is set for a.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |