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 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. Deprecated; the module register interface will be removed in a future version.

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.