[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Symmetric cryptography

The cipher functions are used for symmetrical cryptography, i.e. cryptography using a shared key. The programming model follows an open/process/close paradigm and is in that similar to other building blocks provided by Libgcrypt.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Available ciphers

GCRY_CIPHER_NONE

This is not a real algorithm but used by some functions as error return. The value always evaluates to false.

GCRY_CIPHER_IDEA

This is the IDEA algorithm. The constant is provided but there is currently no implementation for it because the algorithm is patented.

GCRY_CIPHER_3DES

Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but you have to pass 192 bits because the most significant bits of each byte are ignored.

GCRY_CIPHER_CAST5

CAST128-5 block cipher algorithm. The key size is 128 bits.

GCRY_CIPHER_BLOWFISH

The blowfish algorithm. The current implementation allows only for a key size of 128 bits.

GCRY_CIPHER_SAFER_SK128

Reserved and not currently implemented.

GCRY_CIPHER_DES_SK

Reserved and not currently implemented.

GCRY_CIPHER_AES
GCRY_CIPHER_AES128
GCRY_CIPHER_RIJNDAEL
GCRY_CIPHER_RIJNDAEL128

AES (Rijndael) with a 128 bit key.

GCRY_CIPHER_AES192
GCRY_CIPHER_RIJNDAEL192

AES (Rijndael) with a 192 bit key.

GCRY_CIPHER_AES256
GCRY_CIPHER_RIJNDAEL256

AES (Rijndael) with a 256 bit key.

GCRY_CIPHER_TWOFISH

The Twofish algorithm with a 256 bit key.

GCRY_CIPHER_TWOFISH128

The Twofish algorithm with a 128 bit key.

GCRY_CIPHER_ARCFOUR

An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm. Note that this is a stream cipher and must be used very carefully to avoid a couple of weaknesses.

GCRY_CIPHER_DES

Standard DES with a 56 bit key. You need to pass 64 bit but the high bits of each byte are ignored. Note, that this is a weak algorithm which can be broken in reasonable time using a brute force approach.

GCRY_CIPHER_SERPENT128
GCRY_CIPHER_SERPENT192
GCRY_CIPHER_SERPENT256

The Serpent cipher from the AES contest.

GCRY_CIPHER_RFC2268_40
GCRY_CIPHER_RFC2268_128

Ron's Cipher 2 in the 40 and 128 bit variants. Note, that we currently only support the 40 bit variant. The identifier for 128 is reserved for future use.

GCRY_CIPHER_SEED

A 128 bit cipher as described by RFC4269.

GCRY_CIPHER_CAMELLIA128
GCRY_CIPHER_CAMELLIA192
GCRY_CIPHER_CAMELLIA256

The Camellia cipher by NTT. See http://info.isl.ntt.co.jp/crypt/eng/camellia/specifications.html.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Cipher modules

Libgcrypt makes it possible to load additional `cipher modules'; these ciphers can be used just like the cipher algorithms that are built into the library directly. For an introduction into extension modules, see See section Modules.

Data type: gcry_cipher_spec_t

This is the `module specification structure' needed for registering cipher modules, which has to be filled in by the user before it can be used to register a module. It contains the following members:

const char *name

The primary name of the algorithm.

const char **aliases

A list of strings that are `aliases' for the algorithm. The list must be terminated with a NULL element.

gcry_cipher_oid_spec_t *oids

A list of OIDs that are to be associated with the algorithm. The list's last element must have it's `oid' member set to NULL. See below for an explanation of this type.

size_t blocksize

The block size of the algorithm, in bytes.

size_t keylen

The length of the key, in bits.

size_t contextsize

The size of the algorithm-specific `context', that should be allocated for each handle.

gcry_cipher_setkey_t setkey

The function responsible for initializing a handle with a provided key. See below for a description of this type.

gcry_cipher_encrypt_t encrypt

The function responsible for encrypting a single block. See below for a description of this type.

gcry_cipher_decrypt_t decrypt

The function responsible for decrypting a single block. See below for a description of this type.

gcry_cipher_stencrypt_t stencrypt

Like `encrypt', for stream ciphers. See below for a description of this type.

gcry_cipher_stdecrypt_t stdecrypt

Like `decrypt', for stream ciphers. See below for a description of this type.

Data type: gcry_cipher_oid_spec_t

This type is used for associating a user-provided algorithm implementation with certain OIDs. It contains the following members:

const char *oid

Textual representation of the OID.

int mode

Cipher mode for which this OID is valid.

Data type: gcry_cipher_setkey_t

Type for the `setkey' function, defined as: gcry_err_code_t (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned keylen)

Data type: gcry_cipher_encrypt_t

Type for the `encrypt' function, defined as: gcry_err_code_t (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const unsigned char *inbuf)

Data type: gcry_cipher_decrypt_t

Type for the `decrypt' function, defined as: gcry_err_code_t (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const unsigned char *inbuf)

Data type: gcry_cipher_stencrypt_t

Type for the `stencrypt' function, defined as: gcry_err_code_t (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const unsigned char *, unsigned int n)

Data type: gcry_cipher_stdecrypt_t

Type for the `stdecrypt' function, defined as: gcry_err_code_t (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const unsigned char *, unsigned int n)

Function: gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *cipher, unsigned int *algorithm_id, gcry_module_t *module)

Register a new cipher module whose specification can be found in cipher. On success, a new algorithm ID is stored in algorithm_id and a pointer representing this module is stored in module.

Function: void gcry_cipher_unregister (gcry_module_t module)

Unregister the cipher identified by module, which must have been registered with gcry_cipher_register.

Function: gcry_error_t gcry_cipher_list (int *list, int *list_length)

Get a list consisting of the IDs of the loaded cipher modules. If list is zero, write the number of loaded cipher modules to list_length and return. If list is non-zero, the first *list_length algorithm IDs are stored in list, which must be of according size. In case there are less cipher modules than *list_length, *list_length is updated to the correct number.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Available cipher modes

GCRY_CIPHER_MODE_NONE

No mode specified. This should not be used. The only exception is that if Libgcrypt is not used in FIPS mode and if any debug flag has been set, this mode may be used to bypass the actual encryption.

GCRY_CIPHER_MODE_ECB

Electronic Codebook mode.

GCRY_CIPHER_MODE_CFB

Cipher Feedback mode. The shift size equals the block size of the cipher (e.g. for AES it is CFB-128).

GCRY_CIPHER_MODE_CBC

Cipher Block Chaining mode.

GCRY_CIPHER_MODE_STREAM

Stream mode, only to be used with stream cipher algorithms.

GCRY_CIPHER_MODE_OFB

Output Feedback mode.

GCRY_CIPHER_MODE_CTR

Counter mode.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Working with cipher handles

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

Use the following function to release an existing handle:

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.

Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t h, int what, void *buffer, size_t *nbytes)

gcry_cipher_info is used to retrieve various information about a cipher context or the cipher module in general.

Currently no information is available.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 General cipher functions

To work with the algorithms, several functions are available to map algorithm names to the internal identifiers, as well as ways to retrieve information about an algorithm or the current cipher context.

Function: gcry_error_t gcry_cipher_algo_info (int algo, int what, void *buffer, size_t *nbytes)

This function is used to retrieve information on a specific algorithm. You pass the cipher algorithm ID as algo and the type of information requested as what. The result is either returned as the return code of the function or copied to the provided buffer whose allocated length must be available in an integer variable with the address passed in nbytes. This variable will also receive the actual used length of the buffer.

Here is a list of supported codes for what:

GCRYCTL_GET_KEYLEN:

Return the length of the key. If the algorithm supports multiple key lengths, the maximum supported value is returned. The length is returned as number of octets (bytes) and not as number of bits in nbytes; buffer must be zero.

GCRYCTL_GET_BLKLEN:

Return the block length of the algorithm. The length is returned as a number of octets in nbytes; buffer must be zero.

GCRYCTL_TEST_ALGO:

Returns 0 when the specified algorithm is available for use. buffer and nbytes must be zero.

Function: const char * gcry_cipher_algo_name (int algo)

gcry_cipher_algo_name returns a string with the name of the cipher algorithm algo. If the algorithm is not known or another error occurred, the string "?" is returned. This function should not be used to test for the availability of an algorithm.

Function: int gcry_cipher_map_name (const char *name)

gcry_cipher_map_name returns the algorithm identifier for the cipher algorithm described by the string name. If this algorithm is not available 0 is returned.

Function: int gcry_cipher_mode_from_oid (const char *string)

Return the cipher mode associated with an ASN.1 object identifier. The object identifier is expected to be in the IETF-style dotted decimal notation. The function returns 0 for an unknown object identifier or when no mode is associated with it.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on January, 20 2010 using texi2html 1.76.