API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

AEECLSID_CIPHERMODECCM

Brew Release
Brew MP 1.0.2
See Also
ICipherFactory AEEICipher1.h
Description
AEECLSID_CipherModeCCM: Counter with CBC-MAC, CCM, that implements RFC 3610. One should *not* instantiate this class directly. Instead, the class ID, AEECLSID_CipherModeCCM, is to be passed as the mode parameter to ICipherFactory.
CCM is used for two purposes:
1- Generation-Encryption process. 2- Decryption-Verification process.
During the Generation-Encryption process, also known as Encryption- Authentication, the consumer of CCM supplies some parameters to initialize CCM. These parameters are detailed further in this file. During an encryption operation, the consumer of CCM needs to send the additional data and clear text data to ICipher. This is done through the use of ICipher1_Process. The user is free to send the data without any restrictions on buffer sizes or block alignments. The only restriction imposed on the caller is that Adata must be entirely sent first before the payload is sent. This implies that if Adata and the payload are located in one buffer, the user must ensure that Adata is at the beginning of the buffer, followed by the payload to be encrypted. No interleaving of Adata and the Payload is allowed. Other than that restriction, the user is free to send Adata and the payload in a single packet or multi-packet calls to ICipher1_Process. The drawing below depicts a generalized supported packet structure. The structure shows that the user can send the input as n-packets, or in the simplest case, as just one packet; packet (3).
      ________  _________  _________________       __________
     |        ||         ||                 |     |          |
    _| Adata  || Adata   || Adata + Payload | ... | Payload  |
   | |        ||         ||                 |     |          |
   |  ¯¯¯¯¯¯¯¯  ¯¯¯¯¯¯¯¯¯  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯       ¯¯¯¯¯¯¯¯¯¯
   |    (1)        (2)           (3)          ...     (n)
   |            ___________________
   |      \    |                   |
   |_______\   | ICipher1_Process  |
           /   |                   |
          /     ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯


Once packet n, the last packet, has been sent to ICipher1_Process, the caller needs to call ICipher1_ProcessLast to obtain the authentication value of the input. Depending on the output buffer size the user allocated and passed to ICipher1_ProcessLast, the user may need to call ICipher1_ProcessLast in a loop until ICipher1_ProcessLast returns zero bytes. At that point, the CCM operation is complete and the user may then release or reuse ICipher1 resources.

During the Decryption-Verification process, the user sets some parameters as detailed later in this file. Once those parameters are set, the user may then pass the Cipher text along with Adata for Decryption and Verification. The behavior specified for CCM is that the algorithm returns the payload upon successful authentication of the message, otherwise the error AEE_CIPHER_INVALID shall be returned. In this implementation, the payload is returned to the caller before the authenticity of the message is validated. This happens because ICipher does not allocate an arbitrary number of bytes for the output and it does not buffer the input. The caller of ICipher bears that burden. A Failure/Success indication is indicated to the caller as a return code. The user therefore, must check that return code before using the returned decrypted payload, because it can be an invalid payload. This return code will be passed by ICipher1_ProcessLast. The user must always check the error code after each call to ICipher1_ProcessLast, and not jsut the last call, since ICipher1_ProcessLast can return errors before all data is sent to the caller.

The steps needed to perform an Encryption / Decryption operation are illustrated in the figures below. The order of setting those parameters is not important as long as all the parameters are set before any call to ICipher1_Process or ICipher1_ProcessLast takes place.
    ___________________________
   |                           |
   | ICipher1_SetParam : Key   | ----> Sets the key to be used
   |                           |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    ___________________________
   |                           |
   | ICipher1_SetParam : Nonce | ----> Sets the Nonce to be used
   |                           |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    ___________________________
   |                           |
   | ICipher1_SetParam : Tlen  | ----> Valid MAC length in bytes
   |                           |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    ___________________________
   |                           |
   | ICipher1_SetParam : Adata | ----> Adata length, in bytes
   |                           |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

   For Encryption:
    ______________________________________
   |                                      |
   | ICipher1_SetParam: Payload length    | ----> Plen, in bytes
   |                                      |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

   For Decryption:
    ______________________________________
   |                                      |
   | ICipher1_SetParam: Ciphertext length | ----> Clen, in bytes
   |                                      |
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

The format of the input during a Decryption-Verification operation is depicted in the drawing below. The same restrictions apply to this packet structure as those imposed on the encryption operation packets.
      ________  ____________________       ____________       ____________
     |        ||                    |     |            |     |            |
    _| Adata  || Adata + Ciphertext | ... | Ciphertext | ... |    MAC     |
   | |        ||                    |     |            |     |            |
   |  ¯¯¯¯¯¯¯¯  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯       ¯¯¯¯¯¯¯¯¯¯¯¯       ¯¯¯¯¯¯¯¯¯¯¯¯
   |    (1)            (2)            ...      (n)                (m)
   |            ___________________
   |    \      |                   |
   |_____\     | ICipher1_Process  |
         /     |                   |
        /       ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯


Finally, call ICipher1_ProcessLast in a loop until cOutBuff == 0. This applies to both Encryption and Decryption operations. However, during a Decryption operation, the return code from ICipher1_ProcessLast is particularly important, because it indicates whether the returned payload is valid or has failed the authentication process.
               _______________________
              |                       |
   Call ----> | ICipher1_ProcessLast  | ----> cOutBuff
   nErr <---- |                       |
               ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

The behavior of ICipher1_Process and ICipher1_ProcessLast is identical to what is documented in AEEICipher1.h, with the additional constraint on the input packet structure and the additional meaning of the return code from ICipher1_ProcessLast which are both explained in this file.
This implementation was developed and tested for use with AES-128 as per RFC-3610. This implementation should work with any 128 bit block cipher, but has not been tested with other than AES.
The following parameters should be set on the ICipher1 object returned by the factory:
CIPHER_PARAM_CCM_OCTETCNT_M This parameter sets the desired number of octets in the authentication field. The parameter is also referred to as Tlen, which is the desired authentication field size. Supported Tlen sizes are: 4, 6, 8, 10, 12, 14, and 16 bytes.

CIPHER_PARAM_CCM_NONCE This parameter sets the Nonce.

CIPHER_PARAM_CCM_ADDITIONAL_AUTHDATA_LENGTH This parameter sets the length in octets (bytes) of the additional data (also known as Associated data, or Adata) and is generally a header. Adata is used for authentication and is not encrypted as part of the Cipher text output during a Generation-Encryption process.

CIPHER_PARAM_CCM_MESSAGE_LENGTH This parameter sets the message length in octets (bytes.)

CIPHER_PARAM_CCM_CLEN Set the length of the Cipher text passed during the Authentication-Decryption process. This is the length of the Cipher text and does not include the Additional data length.
Default Interface Name