tion 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 *note gnutls_aead_cipher_init:: (gnutls_aead_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY)’
‘INT *note 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 *note 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 *note 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(1).

‘INT *note gnutls_cipher_init:: (gnutls_cipher_hd_t * HANDLE, gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY, const gnutls_datum_t * IV)’
‘INT *note gnutls_cipher_encrypt2:: (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_LEN, void * CTEXT, size_t CTEXT_LEN)’
‘INT *note gnutls_cipher_decrypt2:: (gnutls_cipher_hd_t HANDLE, const void * CTEXT, size_t CTEXT_LEN, void * PTEXT, size_t PTEXT_LEN)’
‘VOID *note gnutls_cipher_set_iv:: (gnutls_cipher_hd_t HANDLE, void * IV, size_t IVLEN)’
‘VOID *note gnutls_cipher_deinit:: (gnutls_cipher_hd_t HANDLE)’

‘INT *note gnutls_cipher_add_auth:: (gnutls_cipher_hd_t HANDLE, const void * PTEXT, size_t PTEXT_SIZE)’
‘INT *note 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.

   ---------- Footnotes ----------

   (1) See the nettle manual
<https://www.lysator.liu.se/~nisse/nettle/nettle.html>