9 Key Derivation

Libgcypt provides a general purpose function to derive keys from strings.

Function: gpg_error_t gcry_kdf_derive ( const void *passphrase, size_t passphraselen, int algo, int subalgo, const void *salt, size_t saltlen, unsigned long iterations, size_t keysize, void *keybuffer )

Derive a key from a passphrase. keysize gives the requested size of the key in octets. keybuffer is a caller provided buffer filled on success with the derived key. The input passphrase is taken from passphrase which is an arbitrary memory buffer of passphraselen octets. algo specifies the KDF algorithm to use; see below. subalgo specifies an algorithm used internally by the KDF algorithms; this is usually a hash algorithm but certain KDF algorithms may use it differently. salt is a salt of length saltlen octets, as needed by most KDF algorithms. iterations is a positive integer parameter to most KDFs.

On success 0 is returned; on failure an error code.

Currently supported KDFs (parameter algo):

GCRY_KDF_SIMPLE_S2K

The OpenPGP simple S2K algorithm (cf. RFC4880). Its use is strongly deprecated. salt and iterations are not needed and may be passed as NULL/0.

GCRY_KDF_SALTED_S2K

The OpenPGP salted S2K algorithm (cf. RFC4880). Usually not used. iterations is not needed and may be passed as 0. saltlen must be given as 8.

GCRY_KDF_ITERSALTED_S2K

The OpenPGP iterated+salted S2K algorithm (cf. RFC4880). This is the default for most OpenPGP applications. saltlen must be given as 8. Note that OpenPGP defines a special encoding of the iterations; however this function takes the plain decoded iteration count.

GCRY_KDF_PBKDF2

The PKCS#5 Passphrase Based Key Derivation Function number 2.

GCRY_KDF_SCRYPT

The SCRYPT Key Derivation Function. The subalgorithm is used to specify the CPU/memory cost parameter N, and the number of iterations is used for the parallelization parameter p. The block size is fixed at 8 in the current implementation.