Symmetric Key Encryption Algorithms

TrustCore SDK supports AES, DES, TripleDES, and Blowfish with at least the CBC mode of operation. For AES, the ECB, CTR, CFB128, OFB, and XTS modes are supported, along with the AEAD modes GCM and CCM. The stream ciphers RC4 and ChaCha20 are also supported. Using other underlying block ciphers such as DES-CBC is analogous, and using other modes of AES such as AES-CTR is similar. Refer to Symmetric algorithms for descriptions of each of these ciphers and modes.

To use the CBC mode of operation:

1. Create a context using the generic BulkCtx type for any of the symmetric key algorithms. Pass in a byte array pKeyData of length 16, 24, or 32 bytes representing the AES key of size 128, 192, or 256 bits respectively. Pass in TRUE for the encrypt flag to perform encryption and not decryption.

   BulkCtx pCtx = NULL; 
   pCtx = CRYPTO_INTERFACE_CreateAESCtx(pKeyData, keyDataLen, TRUE);
   

   This API creates a context specifically for CBC mode; that is, the mode is tied to the context, but to create a context for one of the other modes, you must use one of the following APIs:
   • CRYPTO_INTERFACE_CreateAESCFBCtx
   • CRYPTO_INTERFACE_CreateAESOFBCtx
   • CRYPTO_INTERFACE_CreateAESECBCtx
   • CRYPTO_INTERFACE_CreateAESCTRCtx
   • CRYPTO_INTERFACE_CreateAESXTSCtx

     Note

     There are subtle differences between the APIs you use to create a context. For example, the CRYPTO_INTERFACE_CreateAESCTRCtx API requires the initial 16-byte counter to be appended to the key, rather than be treated as an initialization vector to the next API. Refer to the Crypto Interface API reference for more information.
2. Encrypt the data. An initialization vector (IV) must have been obtained previously, whether random or from another source, and held in a 16byte buffer pIv. The following call may be made as many times as necessary:

   CRYPTO_INTERFACE_DoAES(pCtx, pData, dataLength, TRUE, pIv);
   

   This call encrypts the data in-place (i.e., the buffer pData first holds the input and then the result). For a non-stream cipher mode such as CBC, the dataLength must be a multiple of the cipher’s block-size (i.e., 16-bytes for AES). Also, for CBC mode, the value TRUE for the flag encrypt must match that of context creation. For the NanoCrypto implementation, the buffer pIv is updated in place to the next IV needed for the next call to CRYPTO_INTERFACE_DoAES. The pIv buffer should not be modified in between calls.

   Important

   Some operator implementations of AES-CBC, such as that for TAP, may internally keep track of the IV and do not update the pIv buffer. Future calls to CRYPTO_INTERFACE_DoAES beyond the first ignore the pIv parameter.
3. Clean up the context.

   CRYPTO_INTERFACE_DeleteAESCtx(&pCtx);
   

Complete example

A complete example may be found at:

${MSS_SRC_PKG}/src/crypto_interface/example/crypto_interface_aes_example.c