1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 #ifndef _BSV_CRYPTO_API_H 9 #define _BSV_CRYPTO_API_H 10 11 #ifdef __cplusplus 12 extern "C" 13 { 14 #endif 15 16 /*! @file 17 @brief This file contains cryptographic ROM APIs : SHA256, CMAC KDF, and CCM. 18 */ 19 20 #include "cc_pal_types.h" 21 #include "bsv_crypto_defs.h" 22 #include "cc_sec_defs.h" 23 24 /*---------------------------- 25 PUBLIC FUNCTIONS 26 -----------------------------------*/ 27 28 /*! 29 @brief This function calculates SHA256 digest over contiguous memory in an integrated operation. 30 31 @return CC_OK on success. 32 @return A non-zero value from bsv_error.h on failure. 33 */ 34 CCError_t CC_BsvSHA256( 35 unsigned long hwBaseAddress, /*!< [in] CryptoCell HW registers' base address. */ 36 uint8_t *pDataIn, /*!< [in] Pointer to the input data to be HASHed. Buffer must be contiguous. */ 37 size_t dataSize, /*!< [in] The size of the data to be hashed in Bytes. Limited to 64KB. */ 38 CCHashResult_t hashBuff /*!< [out] Pointer to a word-aligned 32 Byte buffer. */ 39 ); 40 41 /*! 42 @brief The key derivation function is as specified in the "KDF in Counter Mode" section of 43 NIST Special Publication 800-108: Recommendation for Key Derivation Using Pseudorandom Functions. 44 Key derivation is based on length l, label L, context C and derivation key Ki. 45 AES-CMAC is used as the pseudorandom function (PRF). 46 \note When using this API the label and context for each use-case must be well defined. 47 \note We recommend to derive only 256-bit keys from HUK or 256-bit user keys. 48 49 @return CC_OK on success. 50 @return A non-zero value from bsv_error.h on failure. 51 */ 52 53 /* A key derivation functions can iterates n times until l bits of keying material are generated. 54 For each of the iteration of the PRF, i=1 to n, do: 55 result(0) = 0; 56 K(i) = PRF (Ki, [i] || Label || 0x00 || Context || length); 57 results(i) = result(i-1) || K(i); 58 59 concisely, result(i) = K(i) || k(i-1) || .... || k(0)*/ 60 CCError_t CC_BsvKeyDerivation( 61 unsigned long hwBaseAddress, /*!< [in] CryptoCell HW registers' base address. */ 62 CCBsvKeyType_t keyType, /*!< [in] One of the following key types used as an input to a key derivation function: 63 <ul><li>HUK</li> 64 <ul><li>Krtl</li> 65 <ul><li>KCP</li> 66 <ul><li>KPICV</li> 67 <ul><li>128-bit User key</li> 68 <ul><li>256-bit User Key.</li></ul> */ 69 uint32_t *pUserKey, /*!< [in] A pointer to the user's key buffer. */ 70 size_t userKeySize, /*!< [in] The user key size in Bytes (limited to 16Bytes or 32Bytes). */ 71 const uint8_t *pLabel, /*!< [in] A string that identifies the purpose for the derived keying material.*/ 72 size_t labelSize, /*!< [in] The label size. Must be in range of 1 to 8 Bytes in length. */ 73 const uint8_t *pContextData, /*!< [in] A binary string containing the information related to the derived keying material. */ 74 size_t contextSize, /*!< [in] The context size should be in range of 1 to 32 Bytes in length. */ 75 uint8_t *pDerivedKey, /*!< [out] Keying material output. Must be at least the size of derivedKeySize. */ 76 size_t derivedKeySize /*!< [in] Size of the derived keying material in Bytes. Limited to 128bits or 256bits. */ 77 ); 78 79 80 /*! 81 @brief This API allows a limited AES-CCM decrypt and verify operation, needed for AES-CCM verification during boot. 82 AES-CCM combines counter mode encryption with CBC-MAC authentication. 83 Input to CCM includes the following elements: 84 <ul><li> Payload - text data that is both decrypted and verified.</li> 85 <li> Associated data (Adata) - data that is authenticated but not encrypted, e.g., a header.</li> 86 <li> Nonce - A unique value that is assigned to the payload and the associated data.</li></ul> 87 88 @return CC_OK on success. 89 @return A non-zero value on failure as defined bsv_error.h. 90 */ 91 CCError_t CC_BsvAesCcm( 92 unsigned long hwBaseAddress, /*!< [in] CryptoCell HW registers' base address. */ 93 CCBsvCcmKey_t keyBuf, /*!< [in] Pointer to the 128bit AES-CCM key. */ 94 CCBsvCcmNonce_t nonceBuf, /*!< [in] Pointer to the 12 Byte Nonce. */ 95 uint8_t *pAssocData, /*!< [in] Pointer to the associated data. The buffer must be contiguous. */ 96 size_t assocDataSize, /*!< [in] Byte size of the associated data limited to (2^16-2^8) bytes. */ 97 uint8_t *pTextDataIn, /*!< [in] Pointer to the cipher-text data for decryption. The buffer must be contiguous. */ 98 size_t textDataSize, /*!< [in] Byte size of the full text data limited to 64KB. */ 99 uint8_t *pTextDataOut, /*!< [out] Pointer to the output (plain text data). The buffer must be contiguous. */ 100 CCBsvCcmMacRes_t macBuf /*!< [in] Pointer to the MAC result buffer. */ 101 ); 102 103 104 #ifdef __cplusplus 105 } 106 #endif 107 108 #endif 109 110 111 112
