/** * @file api_val_sym.h * * @brief VAL API - Symmetric Cryptography related services */ /***************************************************************************** * Copyright (c) 2014-2018 INSIDE Secure B.V. All Rights Reserved. * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 2 of the License, or * any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . *****************************************************************************/ #ifndef INCLUDE_GUARD_API_VAL_SYM_H #define INCLUDE_GUARD_API_VAL_SYM_H /*----------------------------------------------------------------------------- * This module uses (requires) the following interface(s): */ #include "basic_defs.h" // uint8_t, uint16_t, uint32_t, uint64_t #include "api_val_result.h" // ValStatus_t #include "api_val_buffers.h" // ValOctetsIn_t, ValOctetsOut_t #include "api_val_asset.h" // ValAssetId_t /*---------------------------------------------------------------------------- * Definitions and macros */ /** * Special symmetric crypto related defines: */ /** SHA1/SHA224/SHA256 Blocksize */ #define VAL_SYM_ALGO_HASH_BLOCK_SIZE (512/8) /** SHA384/SHA512 Blocksize */ #define VAL_SYM_ALGO_HASH_SHA512_BLOCK_SIZE (1024/8) /** AES Blocksize */ #define VAL_SYM_ALGO_AES_BLOCK_SIZE (128/8) /** DES Blocksize */ #define VAL_SYM_ALGO_DES_BLOCK_SIZE (64/8) /** ChaCha20 Blocksize */ #define VAL_SYM_ALGO_CHACHA20_BLOCK_SIZE (512/8) /** SM4 Blocksize */ #define VAL_SYM_ALGO_SM4_BLOCK_SIZE (128/8) /** ARIA Blocksize */ #define VAL_SYM_ALGO_ARIA_BLOCK_SIZE (128/8) /** Poly1305 Blocksize */ #define VAL_SYM_ALGO_POLY1305_BLOCK_SIZE (128/8) /** AES IV size */ #define VAL_SYM_ALGO_AES_IV_SIZE (128/8) /** DES IV size */ #define VAL_SYM_ALGO_DES_IV_SIZE (64/8) /** ChaCha20 IV size */ #define VAL_SYM_ALGO_CHACHA20_IV_SIZE (128/8) /** SM4 IV size */ #define VAL_SYM_ALGO_SM4_IV_SIZE (128/8) /** ARIA IV size */ #define VAL_SYM_ALGO_ARIA_IV_SIZE (128/8) /** Maximum IV size used in the interface */ #define VAL_SYM_ALGO_MAX_IV_SIZE VAL_SYM_ALGO_AES_IV_SIZE /** System parameter size */ #define VAL_SYM_ALGO_PARAMETER_SIZE (128/8) /** AES Tag size */ #define VAL_SYM_ALGO_AES_TAG_SIZE (128/8) /** ChaCha20 Tag size */ #define VAL_SYM_ALGO_CHACHA20_TAG_SIZE (128/8) /** Maximum Tag size used in the interface */ #define VAL_SYM_ALGO_MAX_TAG_SIZE VAL_SYM_ALGO_AES_TAG_SIZE /** Maximum block cipher key size */ #define VAL_SYM_ALGO_MAX_CIPHER_KEY_SIZE (256/8) /** Maximum SHA1/SHA224/SHA256 key size */ #define VAL_SYM_ALGO_MAX_SHA2_MAC_KEY_SIZE (512/8) /** Maximum SHA384/SHA512 key size */ #define VAL_SYM_ALGO_MAX_SHA512_MAC_KEY_SIZE (1024/8) /** Maximum MAC key size used in the interface */ #define VAL_SYM_ALGO_MAX_MAC_KEY_SIZE VAL_SYM_ALGO_MAX_SHA512_MAC_KEY_SIZE /** Maximum digest/MAC size used in the interface */ #define VAL_SYM_ALGO_MAX_DIGEST_SIZE (512/8) /** ValSymContextPtr_t - Pointer to the Symmetric Crypto context */ typedef void * ValSymContextPtr_t; /** ValSymContextPtr_Optional_t - Pointer to the optional Symmetric Crypto * context */ typedef ValSymContextPtr_t ValSymContextPtr_Optional_t; /** ValSymAlgo_t - Enumeration for symmetric crypto algorithms */ typedef enum { VAL_SYM_ALGO_NONE = 0, // Not Used/Initialized // Hash algorithms VAL_SYM_ALGO_HASH = 10, // Begin marker VAL_SYM_ALGO_HASH_SHA1, // SHA-1 VAL_SYM_ALGO_HASH_SHA224, // SHA-224 VAL_SYM_ALGO_HASH_SHA256, // SHA-256 VAL_SYM_ALGO_HASH_SHA384, // SHA-384 VAL_SYM_ALGO_HASH_SHA512, // SHA-512 VAL_SYM_ALGO_HASH_MAX, // must be last // MAC algorithms VAL_SYM_ALGO_MAC = 20, // Begin marker VAL_SYM_ALGO_MAC_HMAC_SHA1, // HMAC-SHA-1 VAL_SYM_ALGO_MAC_HMAC_SHA224, // HMAC-SHA-224 VAL_SYM_ALGO_MAC_HMAC_SHA256, // HMAC-SHA-256 VAL_SYM_ALGO_MAC_HMAC_SHA384, // HMAC-SHA-384 VAL_SYM_ALGO_MAC_HMAC_SHA512, // HMAC-SHA-512 VAL_SYM_ALGO_MAC_AES_CMAC, // AES-CMAC VAL_SYM_ALGO_MAC_AES_CBC_MAC, // AES-CBC-MAC VAL_SYM_ALGO_MAC_ARIA_CMAC, // ARIA-CMAC VAL_SYM_ALGO_MAC_ARIA_CBC_MAC, // ARIA-CBC-MAC VAL_SYM_ALGO_MAC_POLY1305, // Poly1305 VAL_SYM_ALGO_MAC_MAX, // must be last // (Block)Cipher algorithms VAL_SYM_ALGO_CIPHER = 40, // Begin marker VAL_SYM_ALGO_CIPHER_AES, // AES VAL_SYM_ALGO_CIPHER_DES, // DES VAL_SYM_ALGO_CIPHER_TRIPLE_DES, // 3DES VAL_SYM_ALGO_CIPHER_CHACHA20, // ChaCha20 VAL_SYM_ALGO_CIPHER_SM4, // SM4 VAL_SYM_ALGO_CIPHER_ARIA, // ARIA VAL_SYM_ALGO_CIPHER_MAX, // must be last } ValSymAlgo_t; /** ValSymMode_t - Enumeration for symmetric crypto modes */ typedef enum { VAL_SYM_MODE_NONE = 0, // Not Used/Initialized // (Block)Cipher modes VAL_SYM_MODE_CIPHER = 30, // Begin marker VAL_SYM_MODE_CIPHER_ECB, // ECB VAL_SYM_MODE_CIPHER_CBC, // CBC VAL_SYM_MODE_CIPHER_CTR, // CTR VAL_SYM_MODE_CIPHER_ICM, // ICM VAL_SYM_MODE_CIPHER_F8, // F8 VAL_SYM_MODE_CIPHER_CCM, // CCM VAL_SYM_MODE_CIPHER_XTS, // XTS VAL_SYM_MODE_CIPHER_GCM, // GCM VAL_SYM_MODE_CIPHER_CHACHA20_ENC, // ChaCha20 Encrypt VAL_SYM_MODE_CIPHER_CHACHA20_AEAD, // ChaCha20 AEAD VAL_SYM_MODE_CIPHER_MAX, // must be last } ValSymMode_t; /** ValSymGCMMode_t - Enumeration for AES-GCM modes */ typedef enum { VAL_SYM_MODE_GCM_NONE = 0, // Not Used/Initialized // GCM modes VAL_SYM_MODE_GCM_GHASH = 40, // GHASH operation with H pre-calculated and Y0-encrypted forced to 0 (IV Truncation operation) VAL_SYM_MODE_GCM_H_PRE_Y0_0, // GCM operation with H pre-calculated and Y0-encrypted forced to 0 VAL_SYM_MODE_GCM_H_PRE_Y0_CALC, // GCM operation with pre-calculated H and Y0-encrypted calculated internally VAL_SYM_MODE_GCM_AUTO, // Autonomous GCM operation (both H and Y0-encrypted calculated internally) VAL_SYM_MODE_GCM_MAX, // must be last } ValSymGCMMode_t; /*----------------------------------------------------------------------------- * val_SymAlloc */ /** * This function allocates and initializes a symmetric crypto context. * Note that decrypt is the default direction for a cipher operation. * * @param [in] Algorithm * The symmetric crypto algorithm of operation. * * @param [in] Mode * Applicable symmetric crypto mode of operation. * * @param [in] fUseTokenTemp * Indication if possible intermediate data (eg. digest, IV) must be * handled via the token. If 'false' the intermediate data is handled * via the Asset Store. * * @param [out] Context_pp * Pointer to the symmetric crypto context pointer in which the allocated * and initialized symmetric crypto context is returned. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymAlloc( ValSymAlgo_t Algorithm, ValSymMode_t Mode, bool fUseTokenTemp, ValSymContextPtr_t * Context_pp); /*----------------------------------------------------------------------------- * val_SymRelease */ /** * This function resets the symmetric crypto operation and releases the * symmetric context. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymRelease( ValSymContextPtr_t const Context_p); /*----------------------------------------------------------------------------- * val_SymInitKey */ /** * This function initializes the key in the symmetric crypto context. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] KeyAssetId * If applicable, the AssetId of the key to use otherwise * VAL_ASSETID_INVALID to indicate that a plaintext key is used * specified with Key_p. * * @param [in] Key_p * If applicable, the pointer to the plaintext key buffer otherwise NULL. * * @param [in] KeySize * The size of the key (KeyLength). * * @return One of the ValStatus_t values. */ ValStatus_t val_SymInitKey( ValSymContextPtr_t const Context_p, ValAssetId_Optional_t KeyAssetId, ValOctetsIn_Optional_t * const Key_p, const ValSize_t KeySize); /*----------------------------------------------------------------------------- * val_SymInitIV */ /** * This function initializes the IV in the symmetric crypto context. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] IV_p * The pointer to the IV buffer. * * @param [in] IVSize * The size of the IV. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymInitIV( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const IV_p, const ValSize_t IVSize); /*----------------------------------------------------------------------------- * val_SymReadTokenTemp */ /** * This function reads/returns the intermediate Digest, MAC, IV, etc.. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @param [out] Temp_p * Pointer to the buffer in which the intermediate data needs to be written. * * @param [in,out] TempSize_p * Pointer to the size of data buffer, upon return it is updated with the * actual size of the intermediate data. * * @param [out] TotalMessageLength_p * Pointer to the total message length, upon return it is written with * total message length. This information is only applicable for Hash and * MAC related operations. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymReadTokenTemp( ValSymContextPtr_t const Context_p, ValOctetsOut_t * const Temp_p, ValSize_t * const TempSize_p, ValSize_t * const TotalMessageLength_p); /*----------------------------------------------------------------------------- * val_SymWriteTokenTemp */ /** * This function writes/sets the intermediate Digest, MAC, IV, etc.. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @param [in] Temp_p * Pointer to the buffer with the intermediate data. * * @param [in] TempSize * Pointer to the size of the intermediate data. * * @param [in] TotalMessageLength * The total message length, which is only applicable for Hash and MAC * related operations. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymWriteTokenTemp( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Temp_p, const ValSize_t TempSize, const ValSize_t TotalMessageLength); /*----------------------------------------------------------------------------- * val_SymHashUpdate */ /** * This function performs a partial hash update. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @param [in] Data_p * Pointer to the buffer with the data that needs to be hashed. * * @param [in] DataSize * The size of the data to be hashed. * Note that the size must be a multiple of the hash block size. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymHashUpdate( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Data_p, const ValSize_t DataSize); /*----------------------------------------------------------------------------- * val_SymHashFinal */ /** * This function performs the final hash update and returns the final digest. * * @param [in] Context_p * Pointer to the symmetric crypto context. * Note: If the operation is successful, the symmetric crypto context * is released. * * @param [in] Data_p * Pointer to the buffer with the data that needs to be hashed. * * @param [in] DataSize * The size of the data to be hashed. * * @param [out] Digest_p * Pointer to a buffer in which the final digest must be returned. * Note: The buffer needs to be big enough to hold the final digest. * * @param [in,out] DigestSize_p * Pointer to the size of digest buffer, upon return it is updated with * the actual size of the final digest. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymHashFinal( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Data_p, const ValSize_t DataSize, ValOctetsOut_t * const Digest_p, ValSize_t * const DigestSize_p); /*----------------------------------------------------------------------------- * val_SymMacUpdate */ /** * This function performs a partial MAC update. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @param [in] Data_p * Pointer to the buffer with the data that needs to be MACed. * * @param [in] DataSize * The size of data to be MACed. * Note that the size must be a multiple of the block size of performed * MAC operation. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymMacUpdate( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Data_p, const ValSize_t DataSize); /*----------------------------------------------------------------------------- * val_SymMacGenerate */ /** * This function performs the final MAC update and returns the final MAC value. * * @param [in] Context_p * Pointer to the symmetric crypto context. * Note: If the operation is successful, the symmetric crypto context * is released. * * @param [in] Data_p * Pointer to the buffer with the data that needs to be MACed. * * @param [in] DataSize * The size of the data to be MACed. * * @param [out] MAC_p * Pointer to a buffer in which the final MAC value must be returned. * Note: The buffer needs to be big enough to hold the final MAC value. * * @param [in,out] MACSize_p * Pointer to the size of MAC value buffer, upon return it is updated with * the actual size of the final MAC value. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymMacGenerate( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Data_p, const ValSize_t DataSize, ValOctetsOut_t * const MAC_p, ValSize_t * const MACSize_p); /*----------------------------------------------------------------------------- * val_SymMacVerify */ /** * This function performs the final MAC update and compares the final MAC * value with the provided one. * * @param [in] Context_p * Pointer to the symmetric crypto context. * Note: If the operation is successful, the symmetric crypto context * is released. * * @param [in] Data_p * Pointer to the buffer with the data that needs to be MACed. * * @param [in] DataSize * The size of the data to be MACed. * * @param [in] MacAssetId * Reference to the Asset that holds the final MAC value or * VAL_ASSETID_INVALID if MAC_p is used to define it. * * @param [in] MAC_p * Pointer to a buffer with the final MAC value that must be checked. * * @param [in] MACSize * The size of the final MAC value. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymMacVerify( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Data_p, const ValSize_t DataSize, ValAssetId_Optional_t const MacAssetId, ValOctetsIn_Optional_t * const MAC_p, const ValSize_t MACSize); /*----------------------------------------------------------------------------- * val_SymCipherInitEncrypt */ /** * This function sets the direction of cipher operation to Encrypt. * Note: This function must be called before the actual cipher operation is * performed * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherInitEncrypt( ValSymContextPtr_t const Context_p); /*----------------------------------------------------------------------------- * val_SymCipherInitParameter */ /** * This function sets the system parameter information. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] Parameter_p * Pointer to a buffer with the parameter. * * @param [in] ParameterSize * The size of the parameter. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherInitParameter( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const Parameter_p, const ValSize_t ParameterSize); /*----------------------------------------------------------------------------- * val_SymCipherInitF8 */ /** * This function sets the specific AES-F8 information. * Note: This function must be called before the actual cipher operation is * performed. * This function can be disabled if the AES-F8 functionality is removed. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] f8SaltKey_p * Pointer to the buffer with the SaltKey. * * @param [in] f8SaltKeySize * The size of the SaltKey. * * @param [in] f8IV_p * Pointer to a buffer with the IV. * * @param [in] f8IVSize * The size of the IV. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherInitF8( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const f8SaltKey_p, const ValSize_t f8SaltKeySize, ValOctetsIn_t * const f8IV_p, const ValSize_t f8IVSize); /*----------------------------------------------------------------------------- * val_SymCipherInitChaCha20 */ /** * This function sets the specific ChaCha20 information. * Note: This function must be called before the actual cipher operation is * performed. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] NonceLength * The length of the Nonce. * Notes: * - Only Nonce length 8 and 12 are allowed. * - The default Nonce length is 12. */ ValStatus_t val_SymCipherInitChaCha20( ValSymContextPtr_t const Context_p, const ValSize_t NonceLength); /*----------------------------------------------------------------------------- * val_SymCipherUpdate */ /** * This function performs a partial cipher update. * * @param [in] Context_p * Pointer to the symmetric crypto context. * * @param [in] SrcData_p * Pointer to the buffer with the data that needs to be de/encrypted. * * @param [in] SrcDataSize * The size of data to be de/encrypted. * Note that the size must be a multiple of the block size of performed * cipher operation. * * @param [out] DstData_p * Pointer to the buffer in which the de/encrypted data needs to be written. * * @param [in,out] DstDataSize_p * Pointer to the size of data buffer, upon return it is updated with * the actual size of the de/encrypted data. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherUpdate( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const SrcData_p, const ValSize_t SrcDataSize, ValOctetsOut_t * const DstData_p, ValSize_t * const DstDataSize_p); /*----------------------------------------------------------------------------- * val_SymCipherFinal */ /** * This function performs a final cipher update. * * @param [in] Context_p * Pointer to the symmetric crypto context. * Note: If the operation is successful, the symmetric crypto context * is released. * * @param [in] SrcData_p * Pointer to the buffer with the data that needs to be de/encrypted. * * @param [in] SrcDataSize * The size of data to be de/encrypted. * Note that the size must be a multiple of the block size of performed * cipher operation. * * @param [out] DstData_p * Pointer to the buffer in which the de/encrypted data needs to be written. * * @param [in,out] DstDataSize_p * Pointer to the size of data buffer, upon return it is updated with * the actual size of the de/encrypted data. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherFinal( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const SrcData_p, const ValSize_t SrcDataSize, ValOctetsOut_t * const DstData_p, ValSize_t * const DstDataSize_p); /*----------------------------------------------------------------------------- * val_SymCipherAEInit */ /** * This function initializes the Authenticated Encryption part in * the symmetric crypto context. * * @param [in,out] Context_p * Pointer to the symmetric crypto context. * * @param [in] NonceHashKey_p * The pointer to the Nonce or Hash key buffer. * * @param [in] NonceHashKeySize * The size of the Nonce or Hash key. * * @param [in] TagSize * The size of the Tag. * * @param [in] GCMMode * The GCM mode to execute. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherAEInit( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const NonceHashKey_p, const ValSize_t NonceHashKeySize, const ValSize_t TagSize, const ValSymGCMMode_t GCMMode); /*----------------------------------------------------------------------------- * val_SymCipherAEFinal */ /** * This function performs a final Authenticated Encryption cipher operation. * The direction is Encrypt if previously val_SymCipherInitEncrypt is called * otherwise it is Decrypt. * * @param [in] Context_p * Pointer to the symmetric crypto context. * Note: If the operation is successful, the symmetric crypto context * is released. * * @param [in] AAD_p * Pointer to the buffer with the Additional Authenticated Data. * * @param [in] AADSize * The size of the Additional Authenticated Data. * * @param [in] SrcData_p * Pointer to the buffer with the data that needs to be de/encrypted. * * @param [in] SrcDataSize * The size of data to be de/encrypted. * Note that the size must be a multiple of the block size of performed * cipher operation. * * @param [out] DstData_p * Pointer to the buffer in which the de/encrypted data needs to be written. * * @param [in,out] DstDataSize_p * Pointer to the size of data buffer, upon return it is updated with * the actual size of the de/encrypted data. * * @param [in,out] Tag_p * Pointer to the buffer in which the Tag is located for a Decrypt * operation or where the Tag needs to be written for an Encrypt operation. * * @param [in,out] TagSize_p * Pointer to the size of the Tag buffer. In, upon return it is updated with * the actual size of the de/encrypted data. * * @return One of the ValStatus_t values. */ ValStatus_t val_SymCipherAEFinal( ValSymContextPtr_t const Context_p, ValOctetsIn_t * const AAD_p, const ValSize_t AADSize, ValOctetsIn_t * const SrcData_p, const ValSize_t SrcDataSize, ValOctetsOut_t * const DstData_p, ValSize_t * const DstDataSize_p, ValOctetsInOut_t * const Tag_p, ValSize_t * const TagSize_p); #endif /* Include Guard */ /* end of file api_val_sym.h */