diff --git a/ChangeLog b/ChangeLog index 28a85b59b13d45444afea6151f1042c4c47e5a0d..de6cacc079cdf12fc12c1ccd1002bb4bac6a1c5f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2014-05-03 Niels Möller <nisse@lysator.liu.se> + * nettle.texinfo (CCM): Document new ccm macros and constants. + Describe ccm restrictions. + * ccm.h (CCM_DIGEST_SIZE): New constant. 2014-04-30 Niels Möller <nisse@lysator.liu.se> diff --git a/nettle.texinfo b/nettle.texinfo index 4e2ec71c45140dcebe58708b72a8b1cdfba42a8f..1a1eb9cc02d58c9d3d59a7fd3f41021ed0662f15 100644 --- a/nettle.texinfo +++ b/nettle.texinfo @@ -2507,41 +2507,14 @@ recommended by NIST in NIST Special Publication 800-38C}. Nettle's support for CCM consists of a low-level general interface, a message encryption and authentication interface, and specific functions for CCM using AES as the underlying -block cipher. These interfaces are defined in @file{<nettle/ccm.h>} +block cipher. These interfaces are defined in @file{<nettle/ccm.h>}. -The inputs to @acronym{CCM} are: -@itemize -@item -A key, which can be used for many messages. -@item -A parameter @var{L} which determines the size of the nonce and the maximum -length of message data which can be processed by @acronym{CCM}. -@item -A tag length, which must be a multiple of 4 bytes up to a maximum of one block. -@item -A nonce which @emph{must} be unique for each message. -@item -Optional authenticated data, which is to be included in the message -authentication, but not encrypted. -@item -The plaintext. May be empty. -@end itemize - -The outputs from @acronym{CCM} are: -@itemize -@item -The ciphertext of the same length as the plaintext. -@item -An encrypted authentication tag, up to one block on length. -@end itemize - -@c FIXME: Focus on the nonce size, set by the caller. -The parameter @var{L} determines the size of the counter that is used -for the message length, such that the maximum message length in bytes is -given by @code{maxlength = (1 << L) - 1}. However increasing @var{L} -also restricts the size of the nonce such that @code{noncelength = -CCM_BLOCK_SIZE - 1 - L}, and throughout this interface the parameter -@var{L} is provided implicitly by the nonce length. +In @acronym{CCM}, the length of the message must be known before +processing. The maximum message size depends on the size of the nonce, +since the message size is encoded in a field which must fit in a single +block, together with the nonce and a flag byte. E.g., with a nonce size +of 12 octets, there are three octets left for encoding the message +length, the maximum message length is @math{2^24 - 1} octets. @acronym{CCM} mode encryption operates as follows: @itemize @@ -2593,6 +2566,21 @@ Holds state corresponding to a particular message. @acronym{CCM}'s block size, 16. @end defvr +@defvr Constant CCM_DIGEST_SIZE +Size of the @acronym{CCM} digest, 16. +@end defvr + +@defvr Constant CCM_MIN_NONCE_SIZE +@defvrx Constant CCM_MAX_NONCE_SIZE +The the minimum and maximum sizes for an @acronym{CCM} nonce, 7 and 14, +respectively. +@end defvr + +@deffn Macro CCM_MAX_MSG_SIZE (@var{nonce_size}) +The largest allowed plaintext length, when using @acronym{CCM} with a +nonce of the given size. +@end deffn + @deftypefun void ccm_set_nonce (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) Initializes @var{ctx} using the given nonce and the sizes of the authenticated data, message, and @acronym{MAC} to be processed.