NAME

EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm — EVP AES cipher in Counter with CBC-MAC mode

SYNOPSIS

#include <openssl/evp.h>

const EVP_CIPHER *
EVP_aes_128_ccm(void);

const EVP_CIPHER *
EVP_aes_192_ccm(void);

const EVP_CIPHER *
EVP_aes_256_ccm(void);

DESCRIPTION

EVP_aes_128_ccm(), EVP_aes_192_ccm(), and EVP_aes_256_ccm() provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit keys in Counter with CBC-MAC (CCM) mode in the evp(3) framework. This mode supports Authenticated Encryption with Additional Data (AEAD) and can be used in a number of communication protocols. Longer keys make precomputation attacks harder at a cost in performance.

For CCM mode ciphers, the behaviour of the EVP interface is subtly altered and several additional EVP_CIPHER_CTX_ctrl(3) operations are required to function correctly. Some of the EVP_CTRL_CCM_* control commands are older aliases for corresponding EVP_CTRL_AEAD_* constants as indicated below.

The less cumbersome and less error-prone EVP_AEAD_CTX_new(3) API does not provide CCM modes. Some communication protocols support alternatives to CCM, which may sometimes allow choosing the better API by avoiding CCM.

Configuration controls

The following two control commands can be issued as soon as EVP_EncryptInit(3) has been called with a CCM type and NULL pointers for key and iv. Both commands are optional and override each other. If issued when a nonce is already set, they silently cause data corruption. The ptr argument is ignored by both; passing NULL is recommended.

EVP_CTRL_CCM_SET_L: Set the size L of the length field to arg bytes and the size of the nonce to 15 - arg bytes. By default, 8 bytes are used for the length field and 7 for the nonce. Selecting a smaller size L for the length field reduces des maximum size of messages that can be sent, but in return allows transmitting more messages with the same key. It is an error to pass less than 2 or more than the default value of 8 for arg.
EVP_CTRL_AEAD_SET_IVLEN (== EVP_CTRL_CCM_SET_IVLEN): Set the size of the nonce to arg bytes and the size L of the length field to 15 - arg bytes. By default, 7 bytes are used for the nonce and 8 for the length field. Selecting a larger size of the nonce allows transmitting more messages with the same key at the expense of reducing the maximum size for each message. It is an error to pass more than 13 or less than the default value of 7 for arg.

After optionally issuing one of the above control commands, EVP_EncryptInit(3) can be called a second time, this time passing NULL for the type argument, with the other two arguments pointing to the desired AES key and to the desired nonce.

Encryption controls

EVP_CTRL_AEAD_SET_TAG (== EVP_CTRL_CCM_SET_TAG): If the ptr argument is NULL, set the tag length M to arg bytes. The default value is 12. Selecting a larger value makes tampering harder for an attacker, at a small expense of making the messages slightly longer. Selecting a smaller value is not recommended. It is an error to pass an odd number for arg, or a number that is less than 4 or greater than 16, or to pass NULL to ptr when ctx is not configured for encrypting. Issuing this control command when an encryption key is already configured silently causes data corruption.
EVP_CTRL_AEAD_GET_TAG (== EVP_CTRL_CCM_GET_TAG): Store the arg bytes of the tag in the memory provided by the caller starting at ptr. It is an error to issue this control command when ctx is not configured for encrypting, when no data was encrypted yet, with an arg that does not match the configured tag length M, or when the tag has already been retrieved earlier.

Before passing any plaintext data to EVP_EncryptUpdate(3), call EVP_EncryptUpdate(3) with both in and out set to NULL, passing the total plaintext length in bytes as in_len. This constructs the first block to be digested with CBC-MAC and copies the text length to *out_len. It does not check whether in_len exceeds the limit of 256^L; the most significant bytes of excessive values are silently discarded.

It is an error if the in_len argument of the EVP_EncryptUpdate(3) call passing the plaintext data does not match the total length specified earlier. Splitting the text into more than one chunks to be passed in multiple calls of EVP_EncryptUpdate(3) is not supported for CCM.

To specify any additional authenticated data (AAD), call EVP_EncryptUpdate(3) with the out argument set to NULL.

Decryption controls

EVP_CTRL_AEAD_SET_TAG (== EVP_CTRL_CCM_SET_TAG): If the ptr argument is not NULL, copy arg bytes starting at ptr to the expected CCM tag value. It is an error to pass an odd number for arg, or a number that is less than 4 or greater than 16. Passing a number that does not correspond to the tag length M that was used for encryption does not raise an error right away, but results in undefined behaviour and typically causes subsequent authentication failure. It is also an error to pass a non-NULL ptr when ctx is configured for encryption.

Before passing any ciphertext data to EVP_DecryptUpdate(3), call EVP_DecryptUpdate(3) with both in and out set to NULL, passing the total ciphertext length in bytes as in_len. This constructs the first block to be digested with CBC-MAC and copies the text length to *out_len. It does not check whether in_len exceeds the limit of 256^L; the most significant bytes of excessive values are silently discarded.

It is an error if the in_len argument of the EVP_DecryptUpdate(3) call passing the ciphertext data does not match the total length specified earlier. Splitting the text into more than one chunks to be passed in multiple calls of EVP_DecryptUpdate(3) is not supported for CCM.

To specify any additional authenticated data (AAD), call EVP_DecryptUpdate(3) with the out argument set to NULL.

If the return value of EVP_DecryptUpdate(3) does not indicate success, the authentication operation may have failed. In that case, regard any output data as corrupted.

Do not call EVP_DecryptFinal(3) when using CCM. Such a call would not do anything useful, and it would fail because the tag that was set with EVP_CTRL_CCM_SET_TAG was already consumed by EVP_DecryptUpdate(3).

RETURN VALUES

These functions return a static constant EVP_CIPHER structure that provides the implementation of the respective AEAD cipher mode.

EXAMPLES

The following code encrypts and digests some secret text and some additional, public data with AES-CCM. Specifically, it implements the Test Vector #1 given in section 8 of RFC 3610.

/* input data */
const unsigned char key[] = {
    0xC0, 0xC1, 0xC2, 0xC3,  0xC4, 0xC5, 0xC6, 0xC7,
    0xC8, 0xC9, 0xCA, 0xCB,  0xCC, 0xCD, 0xCE, 0xCF
};
const unsigned char nonce[] = {
    0x00, 0x00, 0x00, 0x03,  0x02, 0x01, 0x00, 0xA0,
    0xA1, 0xA2, 0xA3, 0xA4,  0xA5
};
const int nonce_len = sizeof(nonce);
const int size_len = 15 - nonce_len;

const unsigned char aad[] = {
    0x00, 0x01, 0x02, 0x03,  0x04, 0x05, 0x06, 0x07
};
const int aad_len = sizeof(aad);

const unsigned char plaintext[] = {
    0x08, 0x09, 0x0A, 0x0B,  0x0C, 0x0D, 0x0E, 0x0F,
    0x10, 0x11, 0x12, 0x13,  0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1A, 0x1B,  0x1C, 0x1D, 0x1E
};
const int text_len = sizeof(plaintext);

/* expected output data */
const unsigned char ciphertext[] = {
    0x58, 0x8C, 0x97, 0x9A,  0x61, 0xC6, 0x63, 0xD2,
    0xF0, 0x66, 0xD0, 0xC2,  0xC0, 0xF9, 0x89, 0x80,
    0x6D, 0x5F, 0x6B, 0x61,  0xDA, 0xC3, 0x84
};

const unsigned char wanted_tag[] = {
    0x17, 0xE8, 0xD1, 0x2C,  0xFD, 0xF9, 0x26, 0xE0
};
const int tag_len = sizeof(wanted_tag);

const int out_len = aad_len + text_len + tag_len;
unsigned char out_buf[out_len];
unsigned char *out_p = out_buf;
unsigned char *out_end = out_buf + out_len;

/* auxiliary variables */
EVP_CIPHER_CTX *ctx;
int irv, i;

/* configuration */
ctx = EVP_CIPHER_CTX_new();
if (ctx == NULL)
	err(1, "EVP_CIPHER_CTX_new");

if (EVP_EncryptInit(ctx, EVP_aes_128_ccm(), NULL, NULL) != 1)
	err(1, "EVP_EncryptInit(NULL)");

if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L,
    size_len, NULL) <= 0)
	err(1, "EVP_CTRL_CCM_SET_L(%d)", size_len);

if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG,
    tag_len, NULL) <= 0)
	err(1, "EVP_CTRL_CCM_SET_TAG(%d)", tag_len);

/* process input data */
if (EVP_EncryptInit(ctx, NULL, key, nonce) != 1)
	err(1, "EVP_EncryptInit(key, nonce)");

if (EVP_EncryptUpdate(ctx, NULL, &irv, NULL, text_len) != 1)
	err(1, "EVP_EncryptUpdate(len = %d)", text_len);
if (irv != text_len)
	errx(1, "text length: want %d, got %d", text_len, irv);

irv = -1;
if (EVP_EncryptUpdate(ctx, NULL, &irv, aad, aad_len) != 1)
	err(1, "EVP_EncryptUpdate(AAD)");
memcpy(out_p, aad, aad_len);
out_p += aad_len;

irv = -1;
if (EVP_EncryptUpdate(ctx, out_p, &irv, plaintext, text_len) != 1)
	err(1, "EVP_EncryptUpdate(plaintext)");
if (irv != text_len)
	errx(1, "text_len: want %d, got %d", text_len, irv);
out_p += irv;

/*
 * EVP_EncryptFinal(3) doesn't really do anything for CCM.
 * Call it anyway to stay closer to normal EVP_Encrypt*(3) idioms,
 * to match what the OpenSSL Wiki suggests since 2013, and to ease
 * later migration of the code to a different AEAD algorithm.
 */
irv = -1;
if (EVP_EncryptFinal(ctx, out_p, &irv) != 1)
	err(1, "EVP_EncryptFinal");
if (irv != 0)
	errx(1, "final_len: want 0, got %d", irv);

/* check output data */
if (memcmp(out_buf + aad_len, ciphertext, text_len) != 0)
	errx(1, "ciphertext mismatch");

if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_GET_TAG,
    tag_len, out_p) <= 0)
	err(1, "EVP_CTRL_CCM_GET_TAG");
if (memcmp(out_p, wanted_tag, tag_len) != 0)
	errx(1, "tag mismatch");
out_p += tag_len;
if (out_p != out_end)
	errx(1, "end of output: want %p, got %p", out_end, out_p);

printf("Total packet length = %d.", out_len);
printf(" [Authenticated and Encrypted Output]");
for (i = 0; i < out_len; i++) {
	if (i % 16 == 0)
		printf("\n         ");
	if (i % 4 == 0)
		putchar(' ');
	printf(" %02X", out_buf[i]);
}
putchar('\n');

EVP_CIPHER_CTX_free(ctx);

The reverse operation for the same test vector, i.e. decrypting and comparing the digest, is implemented by the following code.

The variable declarations and definitions up to the call of EVP_CIPHER_CTX_new(3) are the same as above. The chief differences are:

The tag is not part of the output, so the total output length is shorter.
No memcmp(3) of the tag takes place. Instead, the control command EVP_CTRL_CCM_SET_TAG requires the tag that is going to be verified as an additional argument.
While EVP_EncryptFinal(3) is an optional no-op, EVP_DecryptFinal(3) is not called and would fail.

const int out_len = aad_len + text_len;

/* configuration */
ctx = EVP_CIPHER_CTX_new();
if (ctx == NULL)
	err(1, "EVP_CIPHER_CTX_new");

if (EVP_DecryptInit(ctx, EVP_aes_128_ccm(), NULL, NULL) != 1)
	err(1, "EVP_DecryptInit(NULL)");

if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, size_len, NULL) <= 0)
	err(1, "EVP_CTRL_CCM_SET_L(%d)", size_len);

if (EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG,
    tag_len, (void *)wanted_tag) <= 0)
	err(1, "EVP_CTRL_CCM_SET_TAG(%d)", tag_len);

/* process input data */
if (EVP_DecryptInit(ctx, NULL, key, nonce) != 1)
	err(1, "EVP_DecryptInit(key, nonce)");

if (EVP_DecryptUpdate(ctx, NULL, &irv, NULL, text_len) != 1)
	err(1, "EVP_DecryptUpdate(len = %d)", text_len);
if (irv != text_len)
	errx(1, "text length: want %d, got %d", text_len, irv);

irv = -1;
if (EVP_DecryptUpdate(ctx, NULL, &irv, aad, aad_len) != 1)
	err(1, "EVP_DecryptUpdate(AAD)");
memcpy(out_p, aad, aad_len);
out_p += aad_len;

irv = -1;
if (EVP_DecryptUpdate(ctx, out_p, &irv, ciphertext, text_len) != 1)
	err(1, "EVP_DecryptUpdate(ciphertext)");
if (irv != text_len)
	errx(1, "text_len: want %d, got %d", text_len, irv);
out_p += irv;

/* Do not call EVP_DecryptFinal(3); it would fail and do nothing. */

/* check output data */
if (memcmp(out_buf + aad_len, plaintext, text_len) != 0)
	errx(1, "plaintext mismatch");
if (out_p != out_end)
	errx(1, "end of output: want %p, got %p", out_end, out_p);

printf("Total packet length = %d.", out_len);
printf(" [Decrypted and Authenticated Input]");
for (i = 0; i < out_len; i++) {
	if (i % 16 == 0)
		printf("0        ");
	if (i % 4 == 0)
		putchar(' ');
	printf(" %02X", out_buf[i]);
}
putchar('0);

EVP_CIPHER_CTX_free(ctx);

STANDARDS

Doug Whiting, Russ Housley, and Niels Ferguson, Counter with CBC-MAC (CCM), RFC 3610, September 2003.

HISTORY

EVP_aes_128_ccm(), EVP_aes_192_ccm(), and EVP_aes_256_ccm() first appeared in OpenSSL 1.0.1 and have been available since OpenBSD 5.3.