diff options
Diffstat (limited to 'nettle.texinfo')
-rw-r--r-- | nettle.texinfo | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/nettle.texinfo b/nettle.texinfo index 677a4d3f..699ddb45 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -123,6 +123,7 @@ Authenticated encryption with associated data * CCM:: * ChaCha-Poly1305:: * SIV-CMAC:: +* SIV-GCM:: * nettle_aead abstraction:: Keyed Hash Functions @@ -2880,6 +2881,7 @@ more adventurous alternative, in particular if performance is important. * CCM:: * ChaCha-Poly1305:: * SIV-CMAC:: +* SIV-GCM:: * nettle_aead abstraction:: @end menu @@ -3733,6 +3735,95 @@ are equal, this will return 1 indicating a valid and authenticated message. Otherwise, this function will return zero. @end deftypefun +@node SIV-GCM +@subsection SIV-GCM + +@acronym{SIV-GCM}, described in @cite{RFC 8452}, is an @acronym{AEAD} +construction similar to @acronym{AES-GCM}, but provides protection against +accidental nonce misuse like @acronym{SIV-CMAC} mode. + +It is constructed on top of a block cipher which must have a block size of 128 +bits and a nonce size of 12 bytes. Nettle's support for @acronym{SIV-GCM} +consists of a message encryption and authentication interface, for +@acronym{SIV-GCM} using AES as the underlying block cipher. These +interfaces are defined in @file{<nettle/siv-gcm.h>}. + +Unlike other @acronym{AEAD} mode in @acronym{SIV-GCM} the tag is calculated +over the encoded additional authentication data and plaintext instead of the +ciphertext. + +@subsubsection General interface + +@defvr Constant SIV_GCM_BLOCK_SIZE +@acronym{SIV-GCM}'s block size, 16. +@end defvr + +@defvr Constant SIV_GCM_DIGEST_SIZE +Size of the @acronym{SIV-GCM} digest for tags, 16. +@end defvr + +@defvr Constant SIV_GCM_NONCE_SIZE +Size of the @acronym{SIV-GCM} nonce, 12. +@end defvr + +@deftypefun void siv_gcm_encrypt_message (const struct nettle_cipher *@var{nc}, const void *@var{ctx}, void *@var{ctr_ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Computes the message digest from the @var{adata} and @var{src} +parameters, encrypts the plaintext from @var{src}, appends the +authentication tag to the ciphertext and outputs it to @var{dst}. The +@var{clength} variable must be equal to the length of @var{src} plus +@code{SIV_GCM_DIGEST_SIZE}. +@end deftypefun + +@deftypefun int siv_gcm_decrypt_message (const struct nettle_cipher *@var{nc}, const void *@var{ctx}, void *@var{ctr_ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Decrypts the ciphertext from @var{src}, outputs the plaintext to +@var{dst}, recalculates the initialization vector from @var{adata} and the +plaintext. If the values of the received and calculated initialization vector +are equal, this will return 1 indicating a valid and authenticated +message. Otherwise, this function will return zero. +@end deftypefun + +In the above interface, @var{nc} must point to a cipher that works +with 16-byte block size and the key sizes that are multiple of +8-bytes. The @var{ctx} context structure must be initialized for +encryption mode using a set-key function, before using any of the +functions in this interface. While the @var{ctr_ctx} context +structure must have the same size as @var{ctx}, it does not need to be +initialized before calling those functions as it is used as working +storage. These structures can point to the same area; in that case +the contents of *@var{ctx} is destroyed by the call. + +For convenience, Nettle provides wrapper functions that works with +@acronym{AES} described in the following section. + +@subsubsection @acronym{SIV-GCM}-@acronym{AES} interface + +The @acronym{SIV-GCM} functions provide an API for using @acronym{SIV-GCM} +mode with the @acronym{AES} block ciphers. The parameters all have the same +meaning as the general and message interfaces, except that the @var{cipher}, +@var{f}, and @var{ctx} parameters are replaced with an @acronym{AES} context +structure. The @acronym{AES} context structure must be initialized for +encryption mode using a set-key function, before using any of the functions in +this interface. + +@deftypefun void siv_gcm_aes128_encrypt_message (const struct aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +@deftypefunx void siv_gcm_aes256_encrypt_message (const struct aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Computes the message digest from the @var{adata} and @var{src} +parameters, encrypts the plaintext from @var{src}, appends the +authentication tag to the ciphertext and outputs it to @var{dst}. +The @var{clength} variable must be equal to the length of @var{src} +plus @code{SIV_GCM_DIGEST_SIZE}. + +@end deftypefun + +@deftypefun int siv_gcm_aes128_decrypt_message (const struct aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +@deftypefunx int siv_gcm_aes256_decrypt_message (const struct aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) +Decrypts the ciphertext from @var{src}, outputs the plaintext to +@var{dst}, recalculates the initialization vector from @var{adata} and the +plaintext. If the values of the received and calculated initialization vector +are equal, this will return 1 indicating a valid and authenticated +message. Otherwise, this function will return zero. +@end deftypefun + @node nettle_aead abstraction @subsection The @code{struct nettle_aead} abstraction @cindex nettle_aead |