Commit fe869abe authored by Niels Möller's avatar Niels Möller
Browse files

Updated CCM documentation.

parent 65e69879
2014-05-03 Niels Möller <nisse@lysator.liu.se> 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. * ccm.h (CCM_DIGEST_SIZE): New constant.
2014-04-30 Niels Möller <nisse@lysator.liu.se> 2014-04-30 Niels Möller <nisse@lysator.liu.se>
......
...@@ -2507,41 +2507,14 @@ recommended by NIST in ...@@ -2507,41 +2507,14 @@ recommended by NIST in
NIST Special Publication 800-38C}. Nettle's support for CCM consists of NIST Special Publication 800-38C}. Nettle's support for CCM consists of
a low-level general interface, a message encryption and authentication a low-level general interface, a message encryption and authentication
interface, and specific functions for CCM using AES as the underlying 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: In @acronym{CCM}, the length of the message must be known before
@itemize processing. The maximum message size depends on the size of the nonce,
@item since the message size is encoded in a field which must fit in a single
A key, which can be used for many messages. block, together with the nonce and a flag byte. E.g., with a nonce size
@item of 12 octets, there are three octets left for encoding the message
A parameter @var{L} which determines the size of the nonce and the maximum length, the maximum message length is @math{2^24 - 1} octets.
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.
@acronym{CCM} mode encryption operates as follows: @acronym{CCM} mode encryption operates as follows:
@itemize @itemize
...@@ -2593,6 +2566,21 @@ Holds state corresponding to a particular message. ...@@ -2593,6 +2566,21 @@ Holds state corresponding to a particular message.
@acronym{CCM}'s block size, 16. @acronym{CCM}'s block size, 16.
@end defvr @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}) @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 Initializes @var{ctx} using the given nonce and the sizes of the
authenticated data, message, and @acronym{MAC} to be processed. authenticated data, message, and @acronym{MAC} to be processed.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment