GnuTLS 3.4.3: Cryptographic API

E.12 Cryptographic API

The following functions are to be used for low-level cryptographic operations. Their prototypes lie in gnutls/crypto.h.

gnutls_aead_cipher_decrypt

Function: int gnutls_aead_cipher_decrypt (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const void * auth, size_t auth_len, size_t tag_size, const void * ctext, size_t ctext_len, void * ptext, size_t * ptext_len)

handle: is a gnutls_aead_cipher_hd_t type.

nonce: the nonce to set

nonce_len: The length of the nonce

auth: the data to be authenticated

auth_len: The length of the data

tag_size: The size of the tag to use (use zero for the default)

ctext: the data to decrypt

ctext_len: the length of data to decrypt (includes tag size)

ptext: the decrypted data

ptext_len: the length of decrypted data (initially must hold the maximum available size)

This function will decrypt the given data using the algorithm specified by the context. This function must be provided the whole data to be decrypted, including the tag, and will fail if the tag verification fails.

Returns: Zero or a negative error code on error.

Since: 3.4.0

gnutls_aead_cipher_deinit

Function: void gnutls_aead_cipher_deinit (gnutls_aead_cipher_hd_t handle)

handle: is a gnutls_aead_cipher_hd_t type.

This function will deinitialize all resources occupied by the given authenticated-encryption context.

Since: 3.4.0

gnutls_aead_cipher_encrypt

Function: int gnutls_aead_cipher_encrypt (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const void * auth, size_t auth_len, size_t tag_size, const void * ptext, size_t ptext_len, void * ctext, size_t * ctext_len)

handle: is a gnutls_aead_cipher_hd_t type.

nonce: the nonce to set

nonce_len: The length of the nonce

auth: the data to be authenticated

auth_len: The length of the data

tag_size: The size of the tag to use (use zero for the default)

ptext: the data to encrypt

ptext_len: The length of data to encrypt

ctext: the encrypted data

ctext_len: the length of encrypted data (initially must hold the maximum available size, including space for tag)

This function will encrypt the given data using the algorithm specified by the context. The output data will contain the authentication tag. This function requires that gnutls_aead_cipher_set_nonce() is called before it.

Returns: Zero or a negative error code on error.

Since: 3.4.0

gnutls_aead_cipher_init

Function: int gnutls_aead_cipher_init (gnutls_aead_cipher_hd_t * handle, gnutls_cipher_algorithm_t cipher, const gnutls_datum_t * key)

handle: is a gnutls_aead_cipher_hd_t type.

cipher: the authenticated-encryption algorithm to use

key: The key to be used for encryption

This function will initialize an context that can be used for encryption/decryption of data. This will effectively use the current crypto backend in use by gnutls or the cryptographic accelerator in use.

Returns: Zero or a negative error code on error.

Since: 3.4.0

gnutls_cipher_add_auth

Function: int gnutls_cipher_add_auth (gnutls_cipher_hd_t handle, const void * ptext, size_t ptext_size)

handle: is a gnutls_cipher_hd_t type

ptext: the data to be authenticated

ptext_size: the length of the data

This function operates on authenticated encryption with associated data (AEAD) ciphers and authenticate the input data. This function can only be called once and before any encryption operations.

Returns: Zero or a negative error code on error.

Since: 3.0

gnutls_cipher_decrypt

Function: int gnutls_cipher_decrypt (gnutls_cipher_hd_t handle, void * ctext, size_t ctext_len)

handle: is a gnutls_cipher_hd_t type

ctext: the data to decrypt

ctext_len: the length of data to decrypt

This function will decrypt the given data using the algorithm specified by the context.

Note that in AEAD ciphers, this will not check the tag. You will need to compare the tag sent with the value returned from gnutls_cipher_tag() .

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_cipher_decrypt2

Function: int gnutls_cipher_decrypt2 (gnutls_cipher_hd_t handle, const void * ctext, size_t ctext_len, void * ptext, size_t ptext_len)

handle: is a gnutls_cipher_hd_t type

ctext: the data to decrypt

ctext_len: the length of data to decrypt

ptext: the decrypted data

ptext_len: the available length for decrypted data

This function will decrypt the given data using the algorithm specified by the context.

Note that in AEAD ciphers, this will not check the tag. You will need to compare the tag sent with the value returned from gnutls_cipher_tag() .

Returns: Zero or a negative error code on error.

Since: 2.12.0

gnutls_cipher_deinit

Function: void gnutls_cipher_deinit (gnutls_cipher_hd_t handle)

handle: is a gnutls_cipher_hd_t type

This function will deinitialize all resources occupied by the given encryption context.

Since: 2.10.0

gnutls_cipher_encrypt

Function: int gnutls_cipher_encrypt (gnutls_cipher_hd_t handle, void * ptext, size_t ptext_len)

handle: is a gnutls_cipher_hd_t type

ptext: the data to encrypt

ptext_len: the length of data to encrypt

This function will encrypt the given data using the algorithm specified by the context.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_cipher_encrypt2

Function: int gnutls_cipher_encrypt2 (gnutls_cipher_hd_t handle, const void * ptext, size_t ptext_len, void * ctext, size_t ctext_len)

handle: is a gnutls_cipher_hd_t type

ptext: the data to encrypt

ptext_len: the length of data to encrypt

ctext: the encrypted data

ctext_len: the available length for encrypted data

This function will encrypt the given data using the algorithm specified by the context.

Returns: Zero or a negative error code on error.

Since: 2.12.0

gnutls_cipher_get_block_size

Function: int gnutls_cipher_get_block_size (gnutls_cipher_algorithm_t algorithm)

algorithm: is an encryption algorithm

Returns: the block size of the encryption algorithm.

Since: 2.10.0

gnutls_cipher_get_iv_size

Function: int gnutls_cipher_get_iv_size (gnutls_cipher_algorithm_t algorithm)

algorithm: is an encryption algorithm

Get block size for encryption algorithm.

Returns: block size for encryption algorithm.

Since: 3.2.0

gnutls_cipher_get_tag_size

Function: int gnutls_cipher_get_tag_size (gnutls_cipher_algorithm_t algorithm)

algorithm: is an encryption algorithm

Returns: the tag size of the authenticated encryption algorithm.

Since: 3.2.2

gnutls_cipher_init

Function: int gnutls_cipher_init (gnutls_cipher_hd_t * handle, gnutls_cipher_algorithm_t cipher, const gnutls_datum_t * key, const gnutls_datum_t * iv)

handle: is a gnutls_cipher_hd_t type

cipher: the encryption algorithm to use

key: the key to be used for encryption/decryption

iv: the IV to use (if not applicable set NULL)

This function will initialize the handle context to be usable for encryption/decryption of data. This will effectively use the current crypto backend in use by gnutls or the cryptographic accelerator in use.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_cipher_set_iv

Function: void gnutls_cipher_set_iv (gnutls_cipher_hd_t handle, void * iv, size_t ivlen)

handle: is a gnutls_cipher_hd_t type

iv: the IV to set

ivlen: the length of the IV

This function will set the IV to be used for the next encryption block.

Since: 3.0

gnutls_cipher_tag

Function: int gnutls_cipher_tag (gnutls_cipher_hd_t handle, void * tag, size_t tag_size)

handle: is a gnutls_cipher_hd_t type

tag: will hold the tag

tag_size: the length of the tag to return

This function operates on authenticated encryption with associated data (AEAD) ciphers and will return the output tag.

Returns: Zero or a negative error code on error.

Since: 3.0

gnutls_crypto_register_aead_cipher

Function: int gnutls_crypto_register_aead_cipher (gnutls_cipher_algorithm_t algorithm, int priority, gnutls_cipher_init_func init, gnutls_cipher_setkey_func setkey, gnutls_cipher_aead_encrypt_func aead_encrypt, gnutls_cipher_aead_decrypt_func aead_decrypt, gnutls_cipher_deinit_func deinit)

algorithm: is the gnutls AEAD cipher identifier

priority: is the priority of the algorithm

init: A function which initializes the cipher

setkey: A function which sets the key of the cipher

aead_encrypt: Perform the AEAD encryption

aead_decrypt: Perform the AEAD decryption

deinit: A function which deinitializes the cipher

This function will register a cipher algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90 and CPU-assisted of 80. The algorithm with the lowest priority will be used by gnutls.

In the case the registered init or setkey functions return GNUTLS_E_NEED_FALLBACK , GnuTLS will attempt to use the next in priority registered cipher.

The functions registered will be used with the new AEAD API introduced in GnuTLS 3.4.0. Internally GnuTLS uses the new AEAD API.

Returns: GNUTLS_E_SUCCESS on success, otherwise a negative error code.

Since: 3.4.0

gnutls_crypto_register_cipher

Function: int gnutls_crypto_register_cipher (gnutls_cipher_algorithm_t algorithm, int priority, gnutls_cipher_init_func init, gnutls_cipher_setkey_func setkey, gnutls_cipher_setiv_func setiv, gnutls_cipher_encrypt_func encrypt, gnutls_cipher_decrypt_func decrypt, gnutls_cipher_deinit_func deinit)

algorithm: is the gnutls algorithm identifier

priority: is the priority of the algorithm

init: A function which initializes the cipher

setkey: A function which sets the key of the cipher

setiv: A function which sets the nonce/IV of the cipher (non-AEAD)

encrypt: A function which performs encryption (non-AEAD)

decrypt: A function which performs decryption (non-AEAD)

deinit: A function which deinitializes the cipher

In the case the registered init or setkey functions return GNUTLS_E_NEED_FALLBACK , GnuTLS will attempt to use the next in priority registered cipher.

The functions which are marked as non-AEAD they are not required when registering a cipher to be used with the new AEAD API introduced in GnuTLS 3.4.0. Internally GnuTLS uses the new AEAD API.

Returns: GNUTLS_E_SUCCESS on success, otherwise a negative error code.

Since: 3.4.0

gnutls_crypto_register_digest

Function: int gnutls_crypto_register_digest (gnutls_digest_algorithm_t algorithm, int priority, gnutls_digest_init_func init, gnutls_digest_hash_func hash, gnutls_digest_output_func output, gnutls_digest_deinit_func deinit, gnutls_digest_fast_func hash_fast)

algorithm: is the gnutls digest identifier

priority: is the priority of the algorithm

init: A function which initializes the digest

hash: Perform the hash operation

output: Provide the output of the digest

deinit: A function which deinitializes the digest

hash_fast: Perform the digest operation in one go

This function will register a digest algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90 and CPU-assisted of 80. The algorithm with the lowest priority will be used by gnutls.

Returns: GNUTLS_E_SUCCESS on success, otherwise a negative error code.

Since: 3.4.0

gnutls_crypto_register_mac

Function: int gnutls_crypto_register_mac (gnutls_mac_algorithm_t algorithm, int priority, gnutls_mac_init_func init, gnutls_mac_setkey_func setkey, gnutls_mac_setnonce_func setnonce, gnutls_mac_hash_func hash, gnutls_mac_output_func output, gnutls_mac_deinit_func deinit, gnutls_mac_fast_func hash_fast)

algorithm: is the gnutls MAC identifier

priority: is the priority of the algorithm

init: A function which initializes the MAC

setkey: A function which sets the key of the MAC

setnonce: A function which sets the nonce for the mac (may be NULL for common MAC algorithms)

hash: Perform the hash operation

output: Provide the output of the MAC

deinit: A function which deinitializes the MAC

hash_fast: Perform the MAC operation in one go

This function will register a MAC algorithm to be used by gnutls. Any algorithm registered will override the included algorithms and by convention kernel implemented algorithms have priority of 90 and CPU-assisted of 80. The algorithm with the lowest priority will be used by gnutls.

Returns: GNUTLS_E_SUCCESS on success, otherwise a negative error code.

Since: 3.4.0

gnutls_hash

Function: int gnutls_hash (gnutls_hash_hd_t handle, const void * ptext, size_t ptext_len)

handle: is a gnutls_hash_hd_t type

ptext: the data to hash

ptext_len: the length of data to hash

This function will hash the given data using the algorithm specified by the context.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hash_deinit

Function: void gnutls_hash_deinit (gnutls_hash_hd_t handle, void * digest)

handle: is a gnutls_hash_hd_t type

digest: is the output value of the hash

This function will deinitialize all resources occupied by the given hash context.

Since: 2.10.0

gnutls_hash_fast

Function: int gnutls_hash_fast (gnutls_digest_algorithm_t algorithm, const void * ptext, size_t ptext_len, void * digest)

algorithm: the hash algorithm to use

ptext: the data to hash

ptext_len: the length of data to hash

digest: is the output value of the hash

This convenience function will hash the given data and return output on a single call.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hash_get_len

Function: int gnutls_hash_get_len (gnutls_digest_algorithm_t algorithm)

algorithm: the hash algorithm to use

This function will return the length of the output data of the given hash algorithm.

Returns: The length or zero on error.

Since: 2.10.0

gnutls_hash_init

Function: int gnutls_hash_init (gnutls_hash_hd_t * dig, gnutls_digest_algorithm_t algorithm)

dig: is a gnutls_hash_hd_t type

algorithm: the hash algorithm to use

This function will initialize an context that can be used to produce a Message Digest of data. This will effectively use the current crypto backend in use by gnutls or the cryptographic accelerator in use.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hash_output

Function: void gnutls_hash_output (gnutls_hash_hd_t handle, void * digest)

handle: is a gnutls_hash_hd_t type

digest: is the output value of the hash

This function will output the current hash value and reset the state of the hash.

Since: 2.10.0

gnutls_hmac

Function: int gnutls_hmac (gnutls_hmac_hd_t handle, const void * ptext, size_t ptext_len)

handle: is a gnutls_hmac_hd_t type

ptext: the data to hash

ptext_len: the length of data to hash

This function will hash the given data using the algorithm specified by the context.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hmac_deinit

Function: void gnutls_hmac_deinit (gnutls_hmac_hd_t handle, void * digest)

handle: is a gnutls_hmac_hd_t type

digest: is the output value of the MAC

This function will deinitialize all resources occupied by the given hmac context.

Since: 2.10.0

gnutls_hmac_fast

Function: int gnutls_hmac_fast (gnutls_mac_algorithm_t algorithm, const void * key, size_t keylen, const void * ptext, size_t ptext_len, void * digest)

algorithm: the hash algorithm to use

key: the key to use

keylen: the length of the key

ptext: the data to hash

ptext_len: the length of data to hash

digest: is the output value of the hash

This convenience function will hash the given data and return output on a single call.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hmac_get_len

Function: int gnutls_hmac_get_len (gnutls_mac_algorithm_t algorithm)

algorithm: the hmac algorithm to use

This function will return the length of the output data of the given hmac algorithm.

Returns: The length or zero on error.

Since: 2.10.0

gnutls_hmac_init

Function: int gnutls_hmac_init (gnutls_hmac_hd_t * dig, gnutls_mac_algorithm_t algorithm, const void * key, size_t keylen)

dig: is a gnutls_hmac_hd_t type

algorithm: the HMAC algorithm to use

key: the key to be used for encryption

keylen: the length of the key

This function will initialize an context that can be used to produce a Message Authentication Code (MAC) of data. This will effectively use the current crypto backend in use by gnutls or the cryptographic accelerator in use.

Note that despite the name of this function, it can be used for other MAC algorithms than HMAC.

Returns: Zero or a negative error code on error.

Since: 2.10.0

gnutls_hmac_output

Function: void gnutls_hmac_output (gnutls_hmac_hd_t handle, void * digest)

handle: is a gnutls_hmac_hd_t type

digest: is the output value of the MAC

This function will output the current MAC value and reset the state of the MAC.

Since: 2.10.0

gnutls_hmac_set_nonce

Function: void gnutls_hmac_set_nonce (gnutls_hmac_hd_t handle, const void * nonce, size_t nonce_len)

handle: is a gnutls_hmac_hd_t type

nonce: the data to set as nonce

nonce_len: the length of data

This function will set the nonce in the MAC algorithm.

Since: 3.2.0

gnutls_mac_get_nonce_size

Function: size_t gnutls_mac_get_nonce_size (gnutls_mac_algorithm_t algorithm)

algorithm: is an encryption algorithm

Returns the size of the nonce used by the MAC in TLS.

Returns: length (in bytes) of the given MAC nonce size, or 0.

Since: 3.2.0

gnutls_rnd

Function: int gnutls_rnd (gnutls_rnd_level_t level, void * data, size_t len)

level: a security level

data: place to store random bytes

len: The requested size

This function will generate random data and store it to output buffer.

This function is thread-safe and also fork-safe.

Returns: Zero on success, or a negative error code on error.

Since: 2.12.0

gnutls_rnd_refresh

Function: void gnutls_rnd_refresh ( void)

This function refreshes the random generator state. That is the current precise time, CPU usage, and other values are input into its state.

On a slower rate input from /dev/urandom is mixed too.

Since: 3.1.7