Next: , Previous: Available asymmetric algorithms, Up: AC Interface

6.6.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; a named MPI value is a an MPI value, associated with a label.

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 data sets.

— Data type: gcry_ac_data_t

A single data set.

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. Note that whenever one of the ac functions is about to release objects because of this flag, the objects are expected to be stored in memory allocated through the Libgcrypt memory management. In other words: gcry_free() is used instead of free().
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_COPY, the data set will contain copies of name and mpi. If flags contains GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_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. FIXME: exact semantics undefined.

— 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 (this might be useful for checking the existence of an MPI with extracting it).

— 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.

— Function: gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t data, gcry_sexp_t *sexp, const char **identifiers)

This function converts the data set data into a newly created S-Expression, which is to be stored in sexp; identifiers is a NULL terminated list of C strings, which specifies the structure of the S-Expression.

Example:

If identifiers is a list of pointers to the strings “foo” and “bar” and if data is a data set containing the values “val1 = 0x01” and “val2 = 0x02”, then the resulting S-Expression will look like this: (foo (bar ((val1 0x01) (val2 0x02))).

— Function: gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *data, gcry_sexp_t sexp, const char **identifiers)

This function converts the S-Expression sexp into a newly created data set, which is to be stored in data; identifiers is a NULL terminated list of C strings, which specifies the structure of the S-Expression. If the list of identifiers does not match the structure of the S-Expression, the function fails.