6.6.5 Working with keys

Data type: gcry_ac_key_type_t

Defined constants:

GCRY_AC_KEY_SECRET

Specifies a secret key.

GCRY_AC_KEY_PUBLIC

Specifies a public key.

Data type: gcry_ac_key_t

This type represents a single ‘key’, either a secret one or a public one.

Data type: gcry_ac_key_pair_t

This type represents a ‘key pair’ containing a secret and a public key.

Key data structures can be created in two different ways; a new key pair can be generated, resulting in ready-to-use key. Alternatively a key can be initialized from a given data set.

Function: gcry_error_t gcry_ac_key_init (gcry_ac_key_t *key, gcry_ac_handle_t handle, gcry_ac_key_type_t type, gcry_ac_data_t data)

Creates a new key of type type, consisting of the MPI values contained in the data set data and stores it in key.

Function: gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t handle, unsigned int nbits, void *key_spec, gcry_ac_key_pair_t *key_pair, gcry_mpi_t **misc_data)

Generates a new key pair via the handle handle of NBITS bits and stores it in key_pair.

In case non-standard settings are wanted, a pointer to a structure of type gcry_ac_key_spec_<algorithm>_t, matching the selected algorithm, can be given as key_spec. misc_data is not used yet. Such a structure does only exist for RSA. A description of the members of the supported structures follows.

gcry_ac_key_spec_rsa_t

gcry_mpi_t e

Generate the key pair using a special e. The value of e has the following meanings:

= 0

Let Libgcrypt decide what exponent should be used.

= 1

Request the use of a “secure” exponent; this is required by some specification to be 65537.

> 2

Try starting at this value until a working exponent is found. Note that the current implementation leaks some information about the private key because the incrementation used is not randomized. Thus, this function will be changed in the future to return a random exponent of the given size.

Example code:

{
  gcry_ac_key_pair_t key_pair;
  gcry_ac_key_spec_rsa_t rsa_spec;

  rsa_spec.e = gcry_mpi_new (0);
  gcry_mpi_set_ui (rsa_spec.e, 1);

  err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
  assert (! err);

  err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
                                   &key_pair, NULL);
  assert (! err);
}

Function: gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t key_pair, gcry_ac_key_type_t which)

Returns the key of type which out of the key pair key_pair.

Function: void gcry_ac_key_destroy (gcry_ac_key_t key)

Destroys the key key.

Function: void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t key_pair)

Destroys the key pair key_pair.

Function: gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t key)

Returns the data set contained in the key key.

Function: gcry_error_t gcry_ac_key_test (gcry_ac_handle_t handle, gcry_ac_key_t key)

Verifies that the private key key is sane via handle.

Function: gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t handle, gcry_ac_key_t key, unsigned int *nbits)

Stores the number of bits of the key key in nbits via handle.

Function: gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t handle, gcry_ac_key_t key, unsigned char *key_grip)

Writes the 20 byte long key grip of the key key to key_grip via handle.