Add API to support AEAD cipher modes

* cipher/cipher.c (_gcry_cipher_authenticate, _gcry_cipher_checktag)
(_gcry_cipher_gettag): New.
* doc/gcrypt.texi: Add documentation for new API functions.
* src/visibility.c (gcry_cipher_authenticate, gcry_cipher_checktag)
(gcry_cipher_gettag): New.
* src/gcrypt.h.in, src/visibility.h: add declarations of these
functions.
* src/libgcrypt.defs, src/libgcrypt.vers: export functions.
--

Authenticated Encryption with Associated Data (AEAD) cipher modes
provide authentication tag that can be used to authenticate message. At
the same time it allows one to specify additional (unencrypted data)
that will be authenticated together with the message. This class of
cipher modes requires additional API present in this commit.

This patch is based on original patch by Dmitry Eremin-Solenikov.

Changes in v2:
 - Change gcry_cipher_tag to gcry_cipher_checktag and gcry_cipher_gettag
   for giving tag (checktag) for decryption and reading tag (gettag) after
   encryption.
 - Change gcry_cipher_authenticate to gcry_cipher_setaad, since
   additional parameters needed for some AEAD modes (in this case CCM,
   which needs the length of encrypted data and tag for MAC
   initialization).
 - Add some documentation.

Changes in v3:
 - Change gcry_cipher_setaad back to gcry_cipher_authenticate. Additional
   parameters (encrypt_len, tag_len, aad_len) for CCM will be given
   through GCRY_CTL_SET_CCM_LENGTHS.

Changes in v4:
 - log_fatal => log_error

Signed-off-by: Jussi Kivilinna <jussi.kivilinna@iki.fi>

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index 473c484c..0049fa04 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -1731,6 +1731,10 @@ matches the requirement of the selected algorithm and mode.
 This function is also used with the Salsa20 stream cipher to set or
 update the required nonce.  In this case it needs to be called after
 setting the key.
+
+This function is also used with the AEAD cipher modes to set or
+update the required nonce.
+
 @end deftypefun
 
 @deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l})
@@ -1750,6 +1754,37 @@ call to gcry_cipher_setkey and clear the initialization vector.
 Note that gcry_cipher_reset is implemented as a macro.
 @end deftypefun
 
+Authenticated Encryption with Associated Data (AEAD) block cipher
+modes require the handling of the authentication tag and the additional
+authenticated data, which can be done by using the following
+functions:
+
+@deftypefun gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t @var{h}, const void *@var{abuf}, size_t @var{abuflen})
+
+Process the buffer @var{abuf} of length @var{abuflen} as the additional
+authenticated data (AAD) for AEAD cipher modes.
+
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_gettag (gcry_cipher_hd_t @var{h}, void *@var{tag}, size_t @var{taglen})
+
+This function is used to read the authentication tag after encryption.
+The function finalizes and outputs the authentication tag to the buffer
+@var{tag} of length @var{taglen} bytes.
+
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_checktag (gcry_cipher_hd_t @var{h}, const void *@var{tag}, size_t @var{taglen})
+
+Check the authentication tag after decryption. The authentication
+tag is passed as the buffer @var{tag} of length @var{taglen} bytes
+and compared to internal authentication tag computed during
+decryption.  Error code @code{GPG_ERR_CHECKSUM} is returned if
+the authentication tag in the buffer @var{tag} does not match
+the authentication tag calculated during decryption.
+
+@end deftypefun
+
 The actual encryption and decryption is done by using one of the
 following functions.  They may be used as often as required to process
 all the data.