nettle: CCM
1
1 6.4.3 Counter with CBC-MAC mode
1 -------------------------------
1
1 CCM mode is a combination of counter mode with message authentication
11 based on cipher block chaining, the same building blocks as EAX, ⇒
EAX. It is constructed on top of a block cipher which must have a
1 block size of 128 bits. CCM mode is recommended by NIST in NIST Special
1 Publication 800-38C
1 (http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf).
1 Nettle’s support for CCM consists of a low-level general interface, a
1 message encryption and authentication interface, and specific functions
1 for CCM using AES as the underlying block cipher. These interfaces are
1 defined in ‘<nettle/ccm.h>’.
1
1 In CCM, the length of the message must be known before processing.
1 The maximum message size depends on the size of the nonce, since the
1 message size is encoded in a field which must fit in a single block,
1 together with the nonce and a flag byte. E.g., with a nonce size of 12
1 octets, there are three octets left for encoding the message length, the
1 maximum message length is 2^24 - 1 octets.
1
1 CCM mode encryption operates as follows:
1 • The nonce and message length are concatenated to create ‘B_0 =
1 flags | nonce | mlength’
1
1 • The authenticated data and plaintext is formatted into the string
1 ‘B = L(adata) | adata | padding | plaintext | padding’ with
1 ‘padding’ being the shortest string of zero bytes such that the
1 length of the string is a multiple of the block size, and
1 ‘L(adata)’ is an encoding of the length of ‘adata’.
1
1 • The string ‘B’ is separated into blocks ‘B_1’ ... ‘B_n’
1 • The authentication tag ‘T’ is calculated as ‘T=0, for i=0 to n, do
1 T = E_k(B_i XOR T)’
1
1 • An initial counter is then initialized from the nonce to create ‘IC
1 = flags | nonce | padding’, where ‘padding’ is the shortest string
1 of zero bytes such that ‘IC’ is exactly one block in length.
1
1 • The authentication tag is encrypted using using CTR mode: ‘MAC =
1 E_k(IC) XOR T’
1
1 • The plaintext is then encrypted using CTR mode with an initial
1 counter of ‘IC+1’.
1
1 CCM mode decryption operates similarly, except that the ciphertext
1 and MAC are first decrypted using CTR mode to retreive the plaintext and
1 authentication tag. The authentication tag can then be recalucated from
1 the authenticated data and plantext, and compared to the value in the
1 message to check for authenticity.
1
1 6.4.3.1 General CCM interface
1 .............................
1
1 For all of the functions in the CCM interface, CIPHER is the context
1 struct for the underlying cipher and F is the encryption function. The
1 cipher’s encryption key must be set before calling any of the CCM
1 functions. The cipher’s decryption function and key are never used.
1
1 -- Context struct: struct ccm_ctx
1 Holds state corresponding to a particular message.
1
1 -- Constant: CCM_BLOCK_SIZE
1 CCM’s block size, 16.
1
1 -- Constant: CCM_DIGEST_SIZE
1 Size of the CCM digest, 16.
1
1 -- Constant: CCM_MIN_NONCE_SIZE
1 -- Constant: CCM_MAX_NONCE_SIZE
1 The the minimum and maximum sizes for an CCM nonce, 7 and 14,
1 respectively.
1
1 -- Macro: CCM_MAX_MSG_SIZE (NONCE_SIZE)
1 The largest allowed plaintext length, when using CCM with a nonce
1 of the given size.
1
1 -- Function: void ccm_set_nonce (struct ccm_ctx *CTX, const void
1 *CIPHER, nettle_cipher_func *F, size_t NONCELEN, const uint8_t
1 *NONCE, size_t AUTHLEN, size_t MSGLEN, size_t TAGLEN)
1 Initializes CTX using the given nonce and the sizes of the
1 authenticated data, message, and MAC to be processed.
1
1 -- Function: void ccm_update (struct ccm_ctx *CTX, const void *CIPHER,
1 nettle_cipher_func *F, size_t LENGTH, const uint8_t *DATA)
1 Provides associated data to be authenticated. Must be called after
1 ‘ccm_set_nonce’, and before ‘ccm_encrypt’, ‘ccm_decrypt’, or
1 ‘ccm_digest’.
1
1 -- Function: void ccm_encrypt (struct ccm_ctx *CTX, const void *CIPHER,
1 nettle_cipher_func *F, size_t LENGTH, uint8_t *DST, const
1 uint8_t *SRC)
1 -- Function: void ccm_decrypt (struct ccm_ctx *CTX, const void *CIPHER,
1 nettle_cipher_func *F, size_t LENGTH, uint8_t *DST, const
1 uint8_t *SRC)
1 Encrypts or decrypts the message data. Must be called after
1 ‘ccm_set_nonce’ and before ‘ccm_digest’. All but the last call for
1 each message _must_ use a length that is a multiple of the block
1 size.
1
1 -- Function: void ccm_digest (struct ccm_ctx *CTX, const void *CIPHER,
1 nettle_cipher_func *F, size_t LENGTH, uint8_t *DIGEST)
1 Extracts the message digest (also known “authentication tag”).
1 This is the final operation when processing a message. LENGTH is
1 usually equal to the TAGLEN parameter supplied to ‘ccm_set_nonce’,
1 but if you provide a smaller value, only the first LENGTH octets of
1 the digest are written.
1
1 To encrypt a message using the general CCM interface, set the message
1 nonce and length using ‘ccm_set_nonce’ and then call ‘ccm_update’ to
1 generate the digest of any authenticated data. After all of the
1 authenticated data has been digested use ‘ccm_encrypt’ to encrypt the
1 plaintext. Finally, use ‘ccm_digest’ to return the encrypted MAC.
1
1 To decrypt a message, use ‘ccm_set_nonce’ and ‘ccm_update’ the same
1 as you would for encryption, and then call ‘ccm_decrypt’ to decrypt the
1 ciphertext. After decrypting the ciphertext ‘ccm_digest’ will return
1 the encrypted MAC which should be identical to the MAC in the received
1 message.
1
1 6.4.3.2 CCM message interface
1 .............................
1
1 The CCM message fuctions provides a simple interface that will perform
1 authentication and message encryption in a single function call. The
1 length of the cleartext is given by MLENGTH and the length of the
1 ciphertext is given by CLENGTH, always exactly TLENGTH bytes longer than
1 the corresponding plaintext. The length argument passed to a function
1 is always the size for the result, CLENGTH for the encryption functions,
1 and MLENGTH for the decryption functions.
1
1 -- Function: void ccm_encrypt_message (void *CIPHER, nettle_cipher_func
1 *F, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t CLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 Computes the message digest from the ADATA and SRC parameters,
1 encrypts the plaintext from SRC, appends the encrypted MAC to
1 ciphertext and outputs it to DST.
1
1 -- Function: int ccm_decrypt_message (void *CIPHER, nettle_cipher_func
1 *F, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t MLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 Decrypts the ciphertext from SRC, outputs the plaintext to DST,
1 recalculates the MAC from ADATA and the plaintext, and compares it
1 to the final TLENGTH bytes of SRC. If the values of the received
1 and calculated MACs are equal, this will return 1 indicating a
1 valid and authenticated message. Otherwise, this function will
1 return zero.
1
1 6.4.3.3 CCM-AES interface
1 .........................
1
1 The AES CCM functions provide an API for using CCM mode with the AES
1 block ciphers. The parameters all have the same meaning as the general
1 and message interfaces, except that the CIPHER, F, and CTX parameters
1 are replaced with an AES context structure, and a set-key function must
1 be called before using any of the other functions in this interface.
1
1 -- Context struct: struct ccm_aes128_ctx
1 Holds state corresponding to a particular message encrypted using
1 the AES-128 block cipher.
1
1 -- Context struct: struct ccm_aes192_ctx
1 Holds state corresponding to a particular message encrypted using
1 the AES-192 block cipher.
1
1 -- Context struct: struct ccm_aes256_ctx
1 Holds state corresponding to a particular message encrypted using
1 the AES-256 block cipher.
1
1 -- Function: void ccm_aes128_set_key (struct ccm_aes128_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void ccm_aes192_set_key (struct ccm_aes192_ctx *CTX, const
1 uint8_t *KEY)
1 -- Function: void ccm_aes256_set_key (struct ccm_aes256_ctx *CTX, const
1 uint8_t *KEY)
1 Initializes the encryption key for the AES block cipher. One of
1 these functions must be called before any of the other functions in
1 the AES CCM interface.
1
1 -- Function: void ccm_aes128_set_nonce (struct ccm_aes128_ctx *CTX,
1 size_t NONCELEN, const uint8_t *NONCE, size_t AUTHLEN, size_t
1 MSGLEN, size_t TAGLEN)
1 -- Function: void ccm_aes192_set_nonce (struct ccm_aes192_ctx *CTX,
1 size_t NONCELEN, const uint8_t *NONCE, size_t AUTHLEN, size_t
1 MSGLEN, size_t TAGLEN)
1 -- Function: void ccm_aes256_set_nonce (struct ccm_aes256_ctx *CTX,
1 size_t NONCELEN, const uint8_t *NONCE, size_t AUTHLEN, size_t
1 MSGLEN, size_t TAGLEN)
1 These are identical to ‘ccm_set_nonce’, except that CIPHER, F, and
1 CTX are replaced with a context structure.
1
1 -- Function: void ccm_aes128_update (struct ccm_aes128_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void ccm_aes192_update (struct ccm_aes192_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 -- Function: void ccm_aes256_update (struct ccm_aes256_ctx *CTX, size_t
1 LENGTH, const uint8_t *DATA)
1 These are identical to ‘ccm_set_update’, except that CIPHER, F, and
1 CTX are replaced with a context structure.
1
1 -- Function: void ccm_aes128_encrypt (struct ccm_aes128_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes192_encrypt (struct ccm_aes192_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes256_encrypt (struct ccm_aes256_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes128_decrypt (struct ccm_aes128_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes192_decrypt (struct ccm_aes192_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes256_decrypt (struct ccm_aes256_ctx *CTX,
1 size_t LENGTH, uint8_t *DST, const uint8_t *SRC)
1 These are identical to ‘ccm_set_encrypt’ and ‘ccm_set_decrypt’,
1 except that CIPHER, F, and CTX are replaced with a context
1 structure.
1
1 -- Function: void ccm_aes128_digest (struct ccm_aes128_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void ccm_aes192_digest (struct ccm_aes192_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 -- Function: void ccm_aes256_digest (struct ccm_aes256_ctx *CTX, size_t
1 LENGTH, uint8_t *DIGEST)
1 These are identical to ‘ccm_set_digest’, except that CIPHER, F, and
1 CTX are replaced with a context structure.
1
1 -- Function: void ccm_aes128_encrypt_message (struct ccm_aes128_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t CLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes192_encrypt_message (struct ccm_aes192_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t CLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 -- Function: void ccm_aes256_encrypt_message (struct ccm_aes256_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t CLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 -- Function: int ccm_aes128_decrypt_message (struct ccm_aes128_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t MLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 -- Function: int ccm_aes192_decrypt_message (struct ccm_aes192_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t MLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 -- Function: int ccm_aes192_decrypt_message (struct ccm_aes256_ctx
1 *CTX, size_t NLENGTH, const uint8_t *NONCE, size_t ALENGTH,
1 const uint8_t *ADATA, size_t TLENGTH, size_t MLENGTH, uint8_t
1 *DST, const uint8_t *SRC)
1 These are identical to ‘ccm_encrypt_message’ and
1 ‘ccm_decrypt_message’ except that CIPHER and F are replaced with a
1 context structure.
1