6.3 Public key modules

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

Data type: gcry_pk_spec_t

This is the `module specification structure' needed for registering public key 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 this algorithm.

char **aliases

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

const char *elements_pkey

String containing the one-letter names of the MPI values contained in a public key.

const char *element_skey

String containing the one-letter names of the MPI values contained in a secret key.

const char *elements_enc

String containing the one-letter names of the MPI values that are the result of an encryption operation using this algorithm.

const char *elements_sig

String containing the one-letter names of the MPI values that are the result of a sign operation using this algorithm.

const char *elements_grip

String containing the one-letter names of the MPI values that are to be included in the `key grip'.

int use

The bitwise-OR of the following flags, depending on the abilities of the algorithm:

GCRY_PK_USAGE_SIGN

The algorithm supports signing and verifying of data.

GCRY_PK_USAGE_ENCR

The algorithm supports the encryption and decryption of data.

gcry_pk_generate_t generate

The function responsible for generating a new key pair. See below for a description of this type.

gcry_pk_check_secret_key_t check_secret_key

The function responsible for checking the sanity of a provided secret key. See below for a description of this type.

gcry_pk_encrypt_t encrypt

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

gcry_pk_decrypt_t decrypt

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

gcry_pk_sign_t sign

The function responsible for signing data. See below for a description of this type.

gcry_pk_verify_t verify

The function responsible for verifying that the provided signature matches the provided data. See below for a description of this type.

gcry_pk_get_nbits_t get_nbits

The function responsible for returning the number of bits of a provided key. See below for a description of this type.

Data type: gcry_pk_generate_t

Type for the `generate' function, defined as: gcry_err_code_t (*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)

Data type: gcry_pk_check_secret_key_t

Type for the `check_secret_key' function, defined as: gcry_err_code_t (*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)

Data type: gcry_pk_encrypt_t

Type for the `encrypt' function, defined as: gcry_err_code_t (*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, gcry_mpi_t *pkey, int flags)

Data type: gcry_pk_decrypt_t

Type for the `decrypt' function, defined as: gcry_err_code_t (*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data, gcry_mpi_t *skey, int flags)

Data type: gcry_pk_sign_t

Type for the `sign' function, defined as: gcry_err_code_t (*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, gcry_mpi_t *skey)

Data type: gcry_pk_verify_t

Type for the `verify' function, defined as: gcry_err_code_t (*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data, gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)

Data type: gcry_pk_get_nbits_t

Type for the `get_nbits' function, defined as: unsigned (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)

Function: gcry_error_t gcry_pk_register (gcry_pk_spec_t *pubkey, unsigned int *algorithm_id, gcry_module_t *module)

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

Function: void gcry_pk_unregister (gcry_module_t module)

Unregister the public key module identified by module, which must have been registered with gcry_pk_register.

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

Get a list consisting of the IDs of the loaded pubkey modules. If list is zero, write the number of loaded pubkey 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 pubkey modules than *list_length, *list_length is updated to the correct number.