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.