9.6 Overriding algorithms

In systems which provide a hardware accelerated cipher implementation that is not directly supported by GnuTLS, it is possible to utilize it. There are functions which allow overriding the default cipher, digest and MAC implementations. Those are described below.

To override public key operations see Abstract private keys.

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

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

Deprecated: since 3.7.0 it is no longer possible to override cipher implementation

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

Since: 3.4.0

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.

Deprecated: since 3.7.0 it is no longer possible to override cipher implementation

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

Since: 3.4.0

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.

Deprecated: since 3.7.0 it is no longer possible to override cipher implementation

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

Since: 3.4.0

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.

Deprecated: since 3.7.0 it is no longer possible to override cipher implementation

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

Since: 3.4.0