Working with cipher handles - The Libgcrypt Reference Manual

To use a cipher algorithm, you must first allocate an according handle. This is to be done using the open function:

— Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *hd, int algo, int mode, unsigned int flags)

This function creates the context handle required for most of the other cipher functions and returns a handle to it in `hd'. In case of an error, an according error code is returned.
The ID of algorithm to use must be specified via algo. See See Available ciphers, for a list of supported ciphers and the according constants.
Besides using the constants directly, the function gcry_cipher_map_name may be used to convert the textual name of an algorithm into the according numeric ID.
The cipher mode to use must be specified via mode. See See Available cipher modes, for a list of supported cipher modes and the according constants. Note that some modes are incompatible with some algorithms - in particular, stream mode (GCRY_CIPHER_MODE_STREAM) only works with stream ciphers. Any block cipher mode (GCRY_CIPHER_MODE_ECB, GCRY_CIPHER_MODE_CBC, GCRY_CIPHER_MODE_CFB, GCRY_CIPHER_MODE_OFB or GCRY_CIPHER_MODE_CTR) will work with any block cipher algorithm.
The third argument flags can either be passed as 0 or as the bit-wise OR of the following constants.

GCRY_CIPHER_SECURE
Make sure that all operations are allocated in secure memory. This is useful when the key material is highly confidential.
GCRY_CIPHER_ENABLE_SYNC
This flag enables the CFB sync mode, which is a special feature of Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant. See gcry_cipher_sync.
GCRY_CIPHER_CBC_CTS
Enable cipher text stealing (CTS) for the CBC mode. Cannot be used simultaneous as GCRY_CIPHER_CBC_MAC. CTS mode makes it possible to transform data of almost arbitrary size (only limitation is that it must be greater than the algorithm's block size).
GCRY_CIPHER_CBC_MAC
Compute CBC-MAC keyed checksums. This is the same as CBC mode, but only output the last block. Cannot be used simultaneous as GCRY_CIPHER_CBC_CTS.

— Function: void gcry_cipher_close (gcry_cipher_hd_t h)

This function releases the context created by gcry_cipher_open. It also zeroises all sensitive information associated with this cipher handle.

In order to use a handle for performing cryptographic operations, a `key' has to be set first:

— Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t h, const void *k, size_t l)

Set the key k used for encryption or decryption in the context denoted by the handle h. The length l (in bytes) of the key k must match the required length of the algorithm set for this context or be in the allowed range for algorithms with variable key size. The function checks this and returns an error if there is a problem. A caller should always check for an error.

Most crypto modes requires an initialization vector (IV), which usually is a non-secret random string acting as a kind of salt value. The CTR mode requires a counter, which is also similar to a salt value. To set the IV or CTR, use these functions:

— Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t h, const void *k, size_t l)

Set the initialization vector used for encryption or decryption. The vector is passed as the buffer K of length l bytes and copied to internal data structures. The function checks that the IV matches the requirement of the selected algorithm and mode.

— Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t h, const void *c, size_t l)

Set the counter vector used for encryption or decryption. The counter is passed as the buffer c of length l bytes and copied to internal data structures. The function checks that the counter matches the requirement of the selected algorithm (i.e., it must be the same size as the block size).

— Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t h)

Set the given handle's context back to the state it had after the last call to gcry_cipher_setkey and clear the initialization vector.
Note that gcry_cipher_reset is implemented as a macro.

The actual encryption and decryption is done by using one of the following functions. They may be used as often as required to process all the data.

— Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t h, unsigned char *out, size_t outsize, const unsigned char *in, size_t inlen)

gcry_cipher_encrypt is used to encrypt the data. This function can either work in place or with two buffers. It uses the cipher context already setup and described by the handle h. There are 2 ways to use the function: If in is passed as NULL and inlen is 0, in-place encryption of the data in out or length outsize takes place. With in being not NULL, inlen bytes are encrypted to the buffer out which must have at least a size of inlen. outsize must be set to the allocated size of out, so that the function can check that there is sufficient space. Note that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of the buffers must be a multiple of the block size.
The function returns 0 on success or an error code.

— Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t h, unsigned char *out, size_t outsize, const unsigned char *in, size_t inlen)

gcry_cipher_decrypt is used to decrypt the data. This function can either work in place or with two buffers. It uses the cipher context already setup and described by the handle h. There are 2 ways to use the function: If in is passed as NULL and inlen is 0, in-place decryption of the data in out or length outsize takes place. With in being not NULL, inlen bytes are decrypted to the buffer out which must have at least a size of inlen. outsize must be set to the allocated size of out, so that the function can check that there is sufficient space. Note that overlapping buffers are not allowed.
Depending on the selected algorithms and encryption mode, the length of the buffers must be a multiple of the block size.
The function returns 0 on success or an error code.

OpenPGP (as defined in RFC-2440) requires a special sync operation in some places. The following function is used for this:

— Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t h)

Perform the OpenPGP sync operation on context h. Note that this is a no-op unless the context was created with the flag GCRY_CIPHER_ENABLE_SYNC

Some of the described functions are implemented as macros utilizing a catch-all control function. This control function is rarely used directly but there is nothing which would inhibit it:

— Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t h, int cmd, void *buffer, size_t buflen)

gcry_cipher_ctl controls various aspects of the cipher module and specific cipher contexts. Usually some more specialized functions or macros are used for this purpose. The semantics of the function and its parameters depends on the the command cmd and the passed context handle h. Please see the comments in the source code (src/global.c) for details.

5.4 Working with cipher handles