Owen Kirby osk@exegin.com writes:
Here's a first stab at assembling some documentation about CCM mode and its API.
Thanks! You are aware that the manual is licensed as public domain, is that ok with you?
Some minor nits that I noticed about the API while writing it:
- ccm_decrypt_message uses const void * for the cipher context, but all the other interfaces use void * for this.
Can you be more specific? I think it should be const void * everywhere, and I see no void * in the version of ccm.h which is in the repo. That's one of the things I changed when integrating it.
- passing the clength rather mlength to ccm_decrypt_message could be a little confusing when compared to the rest of the API. In retrospect, I think Neils's initial suggestion on this API was probably the better way to go.
If I remember correctly, we agreed that when we pass the triple (length, dst, src), and the src and destination areas are of diferent sizes, then it's best to adopt the convention that length always is the size of the destination area?
Which then means that ccm_encrypt_message should take clength (length of ciphertext) and ccm_decrypt_message should be changed to take mlength (length of cleartext).
+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
+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.
I think it would be good with a bit more focus on how the caller should select the nonce size. I'd expect that 12 bytes nonce (and the corresponding limit on message size) is the most widely used, following RFC 5116.
What happens if the caller specifies an invalid combination of nonce size and message size? Will it trigger some assert, or will the counter wrap around silently?
Regards, /Niels