17.1 Public-Key Architecture

Because public key cryptography is almost always used to process small amounts of data (hash values or session keys), the interface is not implemented using the open-use-close paradigm, but with single self-contained functions. Due to the wide variety of parameters required by different algorithms S-expressions, as flexible way to convey these parameters, are used. There is a set of helper functions to work with these S-expressions.

Aside of functions to register new algorithms, map algorithms names to algorithms identifiers and to lookup properties of a key, the following main functions are available:

gcry_pk_encrypt

Encrypt data using a public key.

gcry_pk_decrypt

Decrypt data using a private key.

gcry_pk_sign

Sign data using a private key.

gcry_pk_verify

Verify that a signature matches the data.

gcry_pk_testkey

Perform a consistency over a public or private key.

gcry_pk_genkey

Create a new public/private key pair.

All these functions lookup the module implementing the algorithm and pass the actual work to that module. The parsing of the S-expression input and the construction of S-expression for the return values is done by the high level code (cipher/pubkey.c). Thus the internal interface between the algorithm modules and the high level functions passes data in a custom format.

By default Libgcrypt uses a blinding technique for RSA decryption to mitigate real world timing attacks over a network: Instead of using the RSA decryption directly, a blinded value y = x r^{e} \bmod n is decrypted and the unblinded value x' = y' r^{-1} \bmod n returned. The blinding value r is a random value with the size of the modulus n and generated with GCRY_WEAK_RANDOM random level.

The algorithm used for RSA and DSA key generation depends on whether Libgcrypt is operated in standard or in FIPS mode. In standard mode an algorithm based on the Lim-Lee prime number generator is used. In FIPS mode RSA keys are generated as specified in ANSI X9.31 (1998) and DSA keys as specified in FIPS 186-2.