[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | List of algorithms supported by the library. | |
8.2 Working with sets of data | How to work with sets of data. | |
8.3 Working with handles | How to use handles. | |
8.4 Working with keys | How to work with keys. | |
8.5 Using cryptographic functions | How to perform cryptographic operations. | |
8.6 Handle-independent functions | General functions independent of handles. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
Creates a new, empty data set and stores it in data.
Destroys the data set data.
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.
Create a copy of the data set data and store it in data_cp.
Returns the number of named MPI values inside of the data set data.
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.
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.
Destroys any values contained in the data set data.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In order to use an algorithm, an according handle must be created. This is done using the following function:
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.
Destroys the handle handle.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Defined constants:
GCRY_AC_KEY_TYPE_SECRET
Specifies a secret key.
GCRY_AC_KEY_TYPE_PUBLIC
Specifies a public key.
This type represents a single `key', either a secret one or a public one.
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.
Creates a new key of type type, consisting of the MPI values contained in the data set data and stores it in key.
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); } |
Returns the key of type which out of the key pair key_pair.
Destroys the key key.
Destroys the key pair key_pair.
Returns the data set contained in the key key.
Verifies that the private key key is sane via handle.
Stores the number of bits of the key key in nbits via handle.
Writes the 20 byte long key grip of the key key to key_grip via handle.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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.
Signs the data contained in data with the secret key key and stores the resulting signature in the data set 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Stores the textual representation of the algorithm whose id is given in algorithm in name.
Stores the numeric ID of the algorithm whose textual representation is contained in name in algorithm.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on December, 7 2007 using texi2html 1.78.