A couple of utility functions are available to retrieve the length of the key, map algorithm identifiers and perform sanity checks:

— Function: const char * **gcry_pk_algo_name** (`int algo`)

Map the public key algorithm id

algoto a string representation of the algorithm name. For unknown algorithms this functions returns the string`"?"`

. This function should not be used to test for the availability of an algorithm.

— Function: int **gcry_pk_map_name** (`const char *name`)

Map the algorithm

nameto a public key algorithm Id. Returns 0 if the algorithm name is not known.

— Function: int **gcry_pk_test_algo** (`int algo`)

Return 0 if the public key algorithm

algois available for use. Note that this is implemented as a macro.

— Function: unsigned int **gcry_pk_get_nbits** (`gcry_sexp_t key`)

Return what is commonly referred as the key length for the given public or private in

key.

— Function: unsigned char * **gcry_pk_get_keygrip** (`gcry_sexp_t key, unsigned char *array`)

Return the so called "keygrip" which is the SHA-1 hash of the public key parameters expressed in a way depended on the algorithm.

arraymust either provide space for 20 bytes or be`NULL`

. In the latter case a newly allocated array of that size is returned. On success a pointer to the newly allocated space or toarrayis returned.`NULL`

is returned to indicate an error which is most likely an unknown algorithm or one where a "keygrip" has not yet been defined. The function accepts public or secret keys inkey.

— Function: gcry_error_t **gcry_pk_testkey** (`gcry_sexp_t key`)

Return zero if the private key

keyis `sane', an error code otherwise. Note that it is not possible to check the `saneness' of a public key.

— Function: gcry_error_t **gcry_pk_algo_info** (`int algo, int what, void *buffer, size_t *nbytes`)

Depending on the value of

whatreturn various information about the public key algorithm with the idalgo. Note that the function returns`-1`

on error and the actual error code must be retrieved using the function`gcry_errno`

. The currently defined values forwhatare:

`GCRYCTL_TEST_ALGO:`

- Return 0 if the specified algorithm is available for use.
buffermust be`NULL`

,nbytesmay be passed as`NULL`

or point to a variable with the required usage of the algorithm. This may be 0 for "don't care" or the bit-wise OR of these flags:

`GCRY_PK_USAGE_SIGN`

- Algorithm is usable for signing.
`GCRY_PK_USAGE_ENCR`

- Algorithm is usable for encryption.
Unless you need to test for the allowed usage, it is in general better to use the macro gcry_pk_test_algo instead.

`GCRYCTL_GET_ALGO_USAGE:`

- Return the usage flags for the given algorithm. An invalid algorithm return 0. Disabled algorithms are ignored here because we want to know whether the algorithm is at all capable of a certain usage.
`GCRYCTL_GET_ALGO_NPKEY`

- Return the number of elements the public key for algorithm
algoconsist of. Return 0 for an unknown algorithm.`GCRYCTL_GET_ALGO_NSKEY`

- Return the number of elements the private key for algorithm
algoconsist of. Note that this value is always larger than that of the public key. Return 0 for an unknown algorithm.`GCRYCTL_GET_ALGO_NSIGN`

- Return the number of elements a signature created with the algorithm
algoconsists of. Return 0 for an unknown algorithm or for an algorithm not capable of creating signatures.`GCRYCTL_GET_ALGO_NENC`

- Return the number of elements a encrypted message created with the algorithm
algoconsists of. Return 0 for an unknown algorithm or for an algorithm not capable of encryption.Please note that parameters not required should be passed as

`NULL`

.

— Function: gcry_error_t **gcry_pk_ctl** (`int cmd, void *buffer, size_t buflen`)

This is a general purpose function to perform certain control operations.

cmdcontrols what is to be done. The return value is 0 for success or an error code. Currently supported values forcmdare:

`GCRYCTL_DISABLE_ALGO`

- Disable the algorithm given as an algorithm id in
buffer.buffermust point to an`int`

variable with the algorithm id andbuflenmust have the value`sizeof (int)`

.

Libgcrypt also provides a function to generate public key pairs:

— Function: gcry_error_t **gcry_pk_genkey** (`gcry_sexp_t *r_key, gcry_sexp_t parms`)

This function create a new public key pair using information given in the S-expression

parmsand stores the private and the public key in one new S-expression at the address given byr_key. In case of an error,r_keyis set to`NULL`

. The return code is 0 for success or an error code otherwise.Here is an example for

parmsto create an 2048 bit RSA key:(genkey (rsa (nbits 4:2048)))To create an Elgamal key, substitute "elg" for "rsa" and to create a DSA key use "dsa". Valid ranges for the key length depend on the algorithms; all commonly used key lengths are supported. Currently supported parameters are:

`nbits`

- This is always required to specify the length of the key. The argument is a string with a number in C-notation. The value should be a multiple of 8.
`curve`

name- For ECC a named curve may be used instead of giving the number of requested bits. This allows to request a specific curve to override a default selection Libgcrypt would have taken if
`nbits`

has been given. The available names are listed with the description of the ECC public key parameters.`rsa-use-e`

- This is only used with RSA to give a hint for the public exponent. The value will be used as a base to test for a usable exponent. Some values are special:

- ‘
0’- Use a secure and fast value. This is currently the number 41.
- ‘
1’- Use a value as required by some crypto policies. This is currently the number 65537.
- ‘
2’- Reserved
- ‘
> 2’- Use the given value.
If this parameter is not used, Libgcrypt uses for historic reasons 65537.

`qbits`

- This is only meanigful for DSA keys. If it is given the DSA key is generated with a Q parameyer of this size. If it is not given or zero Q is deduced from NBITS in this way:
Note that in this case only the values for N, as given in the table, are allowed. When specifying Q all values of N in the range 512 to 15680 are valid as long as they are multiples of 8.

- ‘
512 <= N <= 1024’- Q = 160
- ‘
N = 2048’- Q = 224
- ‘
N = 3072’- Q = 256
- ‘
N = 7680’- Q = 384
- ‘
N = 15360’- Q = 512
`transient-key`

- This is only meaningful for RSA keys. This is a flag with no value. If given the RSA key is created using a faster and a somewhat less secure random number generator. This flag may be used for keys which are only used for a short time and do not require full cryptographic strength.
`domain`

- This is only meaningful for DLP algorithms. If specified keys are generated with domain parameters taken from this list. The exact format of this parameter depends on the actual algorithm. It is currently only implemented for DSA using this format:
(genkey (dsa (domain (pp-mpi) (qq-mpi) (gq-mpi) (seedseed-mpi) (countercounter-mpi) (hh-mpi))))The

`seed`

,`counter`

and`h`

domain parameters are optional and currently not used.The key pair is returned in a format depending on the algorithm. Both private and public keys are returned in one container and may be accompanied by some miscellaneous information.

As an example, here is what the Elgamal key generation returns:

(key-data (public-key (elg (pp-mpi) (gg-mpi) (yy-mpi))) (private-key (elg (pp-mpi) (gg-mpi) (yy-mpi) (xx-mpi))) (misc-key-info (pm1-factorsn1 n2 ... nn)))As you can see, some of the information is duplicated, but this provides an easy way to extract either the public or the private key. Note that the order of the elements is not defined, e.g. the private key may be stored before the public key.

n1 n2 ... nnis a list of prime numbers used to compositep-mpi; this is in general not a very useful information.