5.4 General cipher functions

To work with the algorithms, several functions are available to map algorithm names to the internal identifiers, as well as ways to retrieve information about an algorithm or the current cipher context.

Function: gcry_error_t gcry_cipher_algo_info (int algo, int what, void *buffer, size_t *nbytes)

This function is used to retrieve information on a specific algorithm. You pass the cipher algorithm ID as algo and the type of information requested as what. The result is either returned as the return code of the function or copied to the provided buffer whose allocated length must be available in an integer variable with the address passed in nbytes. This variable will also receive the actual used length of the buffer.

Here is a list of supported codes for what:

GCRYCTL_GET_KEYLEN:

Return the length of the key. If the algorithm supports multiple key lengths, the maximum supported value is returned. The length is returned as number of octets (bytes) and not as number of bits in nbytes; buffer must be zero. Note that it is usually better to use the convenience function gcry_cipher_get_algo_keylen.

GCRYCTL_GET_BLKLEN:

Return the block length of the algorithm. The length is returned as a number of octets in nbytes; buffer must be zero. Note that it is usually better to use the convenience function gcry_cipher_get_algo_blklen.

GCRYCTL_TEST_ALGO:

Returns 0 when the specified algorithm is available for use. buffer and nbytes must be zero.

Function: size_t gcry_cipher_get_algo_keylen (algo)

This function returns length of the key for algorithm algo. If the algorithm supports multiple key lengths, the maximum supported key length is returned. On error 0 is returned. The key length is returned as number of octets.

This is a convenience functions which should be preferred over gcry_cipher_algo_info because it allows for proper type checking.

Function: size_t gcry_cipher_get_algo_blklen (int algo)

This functions returns the block-length of the algorithm algo counted in octets. On error 0 is returned.

This is a convenience functions which should be preferred over gcry_cipher_algo_info because it allows for proper type checking.

Function: const char * gcry_cipher_algo_name (int algo)

gcry_cipher_algo_name returns a string with the name of the cipher algorithm algo. If the algorithm is not known or another error occurred, the string "?" is returned. This function should not be used to test for the availability of an algorithm.

Function: int gcry_cipher_map_name (const char *name)

gcry_cipher_map_name returns the algorithm identifier for the cipher algorithm described by the string name. If this algorithm is not available 0 is returned.

Function: int gcry_cipher_mode_from_oid (const char *string)

Return the cipher mode associated with an ASN.1 object identifier. The object identifier is expected to be in the IETF-style dotted decimal notation. The function returns 0 for an unknown object identifier or when no mode is associated with it.