9.1 Symmetric algorithms

The available functions to access symmetric crypto algorithms operations are listed in the sections below. The supported algorithms are the algorithms required by the TLS protocol. They are listed in Figure 9.1. Note that there two types of ciphers, the ones providing an authenticated-encryption with associated data (AEAD), and the legacy ciphers which provide raw access to the ciphers. We recommend the use of the AEAD ciphers under the AEAD APIs for new applications as they are designed to minimize the misuse of cryptographic primitives.

Authenticated-encryption API

The AEAD API provides access to all ciphers supported by GnuTLS which support authenticated encryption with associated data; these ciphers are marked with the AEAD keyword on the table above. The AEAD cipher API is particularly suitable for message or packet-encryption as it provides authentication and encryption on the same API. See RFC5116 for more information on authenticated encryption.

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

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)

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)

void gnutls_aead_cipher_deinit (gnutls_aead_cipher_hd_t handle)

Because the encryption function above may be difficult to use with scattered data, we provide the following API.

Function: int gnutls_aead_cipher_encryptv (gnutls_aead_cipher_hd_t handle, const void * nonce, size_t nonce_len, const giovec_t * auth_iov, int auth_iovcnt, size_t tag_size, const giovec_t * iov, int iovcnt, 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_iov: additional data to be authenticated

auth_iovcnt: The number of buffers in auth_iov

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

iov: the data to be encrypted

iovcnt: The number of buffers in iov

ctext: the encrypted data including authentication tag

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

This function will encrypt the provided data buffers using the algorithm specified by the context. The output data will contain the authentication tag.

Returns: Zero or a negative error code on error.

Since: 3.6.3

Legacy API

The legacy API provides low-level access to all legacy ciphers supported by GnuTLS, and some of the AEAD ciphers (e.g., AES-GCM and CHACHA20). The restrictions of the nettle library implementation of the ciphers apply verbatim to this API²².

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

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

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

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

void gnutls_cipher_deinit (gnutls_cipher_hd_t handle)

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

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

While the latter two functions allow the same API can be used with authenticated encryption ciphers, it is recommended to use the following functions which are solely for AEAD ciphers. The latter API is designed to be simple to use and also hard to misuse, by handling the tag verification and addition in transparent way.