8. Public Key cryptography (II)

This chapter documents the alternative interface to asymmetric cryptography (ac) that is not based on S-expressions, but on native C data structures. As opposed to the pk interface described in the former chapter, this one follows an open/use/close paradigm like other building blocks of the library.

8.1 Available asymmetric algorithms

Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well as DSA (Digital Signature Algorithm) and ElGamal. The versatile interface allows to add more algorithms in the future.

Data type: gcry_ac_id_t

The following constants are defined for this type:

GCRY_AC_RSA

Riven-Shamir-Adleman

GCRY_AC_DSA

Digital Signature Algorithm

GCRY_AC_ELG

ElGamal

GCRY_AC_ELG_E

ElGamal, encryption only.

8.2 Working with sets of data

In the context of this interface the term `data set' refers to a list of `named MPI values' that is used by functions performing cryptographic operations.

Such data sets are used for representing keys, since keys simply consist of a variable amount of numbers. Furthermore some functions return data sets to the caller that are to be provided to other functions.

This section documents the data types, symbols and functions that are relevant for working with such data sets.

Data type: gcry_ac_data_t

A data set, that is simply a list of named MPI values.

The following flags are supported:

GCRY_AC_FLAG_DEALLOC

Used for storing data in a data set. If given, the data will be released by the library.

GCRY_AC_FLAG_COPY

Used for storing/retrieving data in/from a data set. If given, the library will create copies of the provided/contained data, which will then be given to the user/associated with the data set.

Function: gcry_error_t gcry_ac_data_new (gcry_ac_data_t *data)

Creates a new, empty data set and stores it in data.

Function: void gcry_ac_data_destroy (gcry_ac_data_t data)

Destroys the data set data.

Function: gcry_error_t gcry_ac_data_set (gcry_ac_data_t data, unsigned int flags, char *name, gcry_mpi_t mpi)

Add the value mpi to data with the label name. If flags contains GCRY_AC_FLAG_DATA_COPY, the data set will contain copies of name and mpi. If flags contains GCRY_AC_FLAG_DATA_DEALLOC or GCRY_AC_FLAG_DATA_COPY, the values contained in the data set will be deallocated when they are to be removed from the data set.

Function: gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *data_cp, gcry_ac_data_t data)

Create a copy of the data set data and store it in data_cp.

Function: unsigned int gcry_ac_data_length (gcry_ac_data_t data)

Returns the number of named MPI values inside of the data set data.

Function: gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t data, unsigned int flags, char *name, gcry_mpi_t *mpi)

Store the value labelled with name found in data in mpi. If flags contains GCRY_AC_FLAG_COPY, store a copy of the mpi value contained in the data set. mpi may be NULL.

Function: gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t data, unsigned int flags, unsigned int index, const char **name, gcry_mpi_t *mpi)

Stores in name and mpi the named mpi value contained in the data set data with the index idx. If flags contains GCRY_AC_FLAG_COPY, store copies of the values contained in the data set. name or mpi may be NULL.

Function: void gcry_ac_data_clear (gcry_ac_data_t data)

Destroys any values contained in the data set data.

8.3 Working with handles

In order to use an algorithm, an according handle must be created. This is done using the following function:

Function: gcry_error_t gcry_ac_open (gcry_ac_handle_t *handle, int algorithm, int flags)

Creates a new handle for the algorithm algorithm and stores it in handle. flags is not used yet.

algorithm must be a valid algorithm ID, see See section Available algorithms, for a list of supported algorithms and the according constants. Besides using the listed constants directly, the functions gcry_ac_name_to_id may be used to convert the textual name of an algorithm into the according numeric ID.

Function: void gcry_ac_close (gcry_ac_handle_t handle)

Destroys the handle handle.

8.4 Working with keys

Data type: gcry_ac_key_type_t

Defined constants:

GCRY_AC_KEY_TYPE_SECRET

Specifies a secret key.

GCRY_AC_KEY_TYPE_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 descriptions 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 device 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 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, &key_pair, 1024, (void *) &rsa_spec); 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.

8.5 Using cryptographic functions

The following flags might be relevant:

GCRY_AC_FLAG_NO_BLINDING

Disable any blinding, which might be supported by the chosen algorithm; blinding is the default.

Function: gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t handle, unsigned int flags, gcry_ac_key_t key, gcry_mpi_t data_plain, gcry_ac_data_t **data_encrypted)

Encrypts the plain text MPI value data_plain with the key public key under the control of the flags flags and stores the resulting data set into data_encrypted.

Function: gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t handle, unsigned int flags, gcry_ac_key_t key, gcry_mpi_t *data_plain, gcry_ac_data_t data_encrypted)

Decrypts the encrypted data contained in the data set data_encrypted with the secret key KEY under the control of the flags flags and stores the resulting plain text MPI value in DATA_PLAIN.

Function: gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t handle, gcry_ac_key_t key, gcry_mpi_t data, gcry_ac_data_t *data_signature)

Signs the data contained in data with the secret key key and stores the resulting signature in the data set data_signature.

Function: gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t handle, gcry_ac_key_t key, gcry_mpi_t data, gcry_ac_data_t data_signature)

Verifies that the signature contained in the data set data_signature is indeed the result of signing the data contained in data with the secret key belonging to the public key key.

8.6 Handle-independent functions

Function: gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t algorithm, const char **name)

Stores the textual representation of the algorithm whose id is given in algorithm in name.

Function: gcry_error_t gcry_ac_name_to_id (const char *name, gcry_ac_id_t *algorithm)

Stores the numeric ID of the algorithm whose textual representation is contained in name in algorithm.

This document was generated by Super-User on June, 10 2008 using texi2html 1.78.