[RFC PATCH 2/3] Add API for initializing AEAD modes

[Jussi Kivilinna]

On 13.10.2013 13:45, Werner Koch wrote:
> On Sun, 13 Oct 2013 12:02, jussi.kivilinna at iki.fi said:
> 
>> CCM mode needs to know length of encrypted data in advance. So, would it make
>> sense to add variadic API function for initilizing AEAD mode? The one that
> 
> Let's talks about this api first.  I need to look closer at it.

Sure.

I based CCM patchset on the AEAD API patch Dmitry sent earlier for GCM. Since CCM
has more restrictions (need to know data lengths in advance) than GCM, I added
gcry_cipher_aead_init.

With this patchset to encrypt a buffer using CCM, you'd first need to
initialize/reset CCM state with:

gcry_cipher_aead_init (hd, nonce_buf, nonce_len, authtag_len, plaintext_len)

CCM needs tag and plaintext lengths for MAC initialization. CCM also needs
length of AAD (additional authenticated data) for MAC, so this call is followed by:

gcry_cipher_authenticate (hd, aadbuf, aadbuflen)

which does the actual MAC initialization. If aadbuflen == 0, then above call can be
omitted and gcry_cipher_(en|de)crypt will call gcry_cipher_authenticate with zero
length.

Plaintext can then be encrypted with:

gcry_cipher_encrypt (hd, ciphertext_buf, ciphertext_len, plaintext_buf, plaintext_len)

where ciphertext_len >= plaintext_len + authtag_len.

Ciphertext can be decrypted with:

gcry_cipher_decrypt (hd, plaintext_buf, plaintext_len, ciphertext_buf, ciphertext_len)

NIST paper and RFC 3610 define CCM ciphertext as [ctr-enc(plaintext) || authtag]
and that decryption must not reveal any information (plaintext or authtag) if
authtag is not correct. Therefore full buffers, matching with length of plaintext_len
and authtag_len given in gcry_cipher_aead_init, have to be used. If authentication
check fails, decrypt function clears output buffer and internal authtag buffer.

> Did you notice the new gcry_buffer_t ?

Yes, I did.

Would it be better to add functions to do AEAD encrypt/decrypt in single go and use
gcry_buffer_t? This would avoid having internal state machines in AEAD modes and having
to call different functions in correct order.

gcry_cipher_aead_encrypt (hd, gcry_buffer_t ct_buf, ct_len, gcry_buffer_t pt_buf, pt_len,
			  gcry_buffer_t aad_buf, aad_len, nonce, nonce_len)

For CCM, authentication tag length could be calculated from ct_len - pt_len.

-Jussi

> 
> 
> Salam-Shalom,
> 
>    Werner
>