summaryrefslogtreecommitdiff
path: root/doc/cha-crypto.texi
diff options
context:
space:
mode:
authorNikos Mavrogiannopoulos <nmav@gnutls.org>2018-06-02 21:25:10 +0200
committerNikos Mavrogiannopoulos <nmav@redhat.com>2018-06-14 16:30:45 +0200
commit9a714f6047e18a30d0c2de771933e0f297f4b58f (patch)
tree908faf326e5551cf44fc27c514f565e51407d3f1 /doc/cha-crypto.texi
parentaa54b849c102e9cc433201f849f1e8ad029a9a80 (diff)
downloadgnutls-9a714f6047e18a30d0c2de771933e0f297f4b58f.tar.gz
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>
Diffstat (limited to 'doc/cha-crypto.texi')
-rw-r--r--doc/cha-crypto.texi32
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