gnutls_aead_cipher_encryptv: introduced

This API allows encryption using a scatter input, by also
taking advantage of ciphers which are optimized for such input.
That is particularly useful under TLS1.3 since its encryption is
based on encryption of scattered data (data+pad).

Resolves #458

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

1 files changed, 28 insertions, 4 deletions

diff --git a/doc/cha-crypto.texi b/doc/cha-crypto.texi
index dc28a42a94..ab5f9ac15f 100644
--- a/doc/cha-crypto.texi
+++ b/doc/cha-crypto.texi
@@ -23,11 +23,37 @@ to the random number generation. For a low-level crypto API the usage of nettle
 @cindex symmetric cryptography
 
 The available functions to access symmetric crypto algorithms operations
-are shown below. The supported algorithms are the algorithms required by the TLS protocol.
-They are listed in @ref{gnutls_cipher_algorithm_t}.
+are listed in the sections below. The supported algorithms are the algorithms required by the TLS protocol.
+They are listed in @ref{gnutls_cipher_algorithm_t}. 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 APIs for new applications
+as it is designed to minimize misuse of cryptography.
 
 @showenumdesc{gnutls_cipher_algorithm_t,The supported ciphers.}
 
+@subheading Authenticated-encryption API
+
+The AEAD API provides access to all ciphers supported by GnuTLS which support
+authenticated encryption with associated data. That is particularly suitable
+for message or packet-encryption as it provides authentication and
+encryption on the same API. See @code{RFC5116} for more information on
+authenticated encryption.
+
+@showfuncD{gnutls_aead_cipher_init,gnutls_aead_cipher_encrypt,gnutls_aead_cipher_decrypt,gnutls_aead_cipher_deinit}
+
+Because the encryption function above may be difficult to use with
+scattered data, we provide the following API.
+
+@showfuncdesc{gnutls_aead_cipher_encryptv}
+
+@subheading 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@footnote{See the nettle manual @url{https://www.lysator.liu.se/~nisse/nettle/nettle.html}}.
+
 @showfuncE{gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit}
 
 @showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}
@@ -36,8 +62,6 @@ it is recommended to use the following functions which are solely for AEAD ciphe
 API is designed to be simple to use and also hard to misuse, by handling the tag verification
 and addition in transparent way.
 
-@showfuncD{gnutls_aead_cipher_init,gnutls_aead_cipher_encrypt,gnutls_aead_cipher_decrypt,gnutls_aead_cipher_deinit}
-
 @node Public key algorithms
 @section Public key algorithms
 @cindex public key algorithms