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 @addtogroup cc_utils_key_derivation 9 @{ 10 */ 11 12 /*! 13 @file 14 @brief This file contains the CryptoCell utility key-derivation function APIs. 15 16 The key-derivation function is defined as specified in the 17 <em>KDF in Counter Mode</em> section in <em>NIST Special Publication 18 800-108: Recommendation for Key Derivation Using Pseudorandom Functions</em>. 19 */ 20 21 #ifndef _MBEDTLS_CC_UTIL_KEY_DERIVATION_H 22 #define _MBEDTLS_CC_UTIL_KEY_DERIVATION_H 23 24 #ifdef __cplusplus 25 extern "C" 26 { 27 #endif 28 29 30 #include "mbedtls_cc_util_defs.h" 31 #include "mbedtls_cc_util_key_derivation_defs.h" 32 #include "cc_hash_defs.h" 33 34 /****************************************************************************** 35 * DEFINITIONS 36 ******************************************************************************/ 37 38 /*! Derivation type of the input key. */ 39 typedef enum { 40 /*! The user key.*/ 41 CC_UTIL_USER_KEY = 0, 42 /*! The device root key (the HUK).*/ 43 CC_UTIL_ROOT_KEY = 1, 44 /*! Total number of keys.*/ 45 CC_UTIL_TOTAL_KEYS = 2, 46 /*! Reserved.*/ 47 CC_UTIL_END_OF_KEY_TYPE = 0x7FFFFFFF 48 }mbedtls_util_keytype_t; 49 50 /*! Pseudo-random function type for key derivation. */ 51 typedef enum { 52 /*! The CMAC function.*/ 53 CC_UTIL_PRF_CMAC = 0, 54 /*! The HMAC function.*/ 55 CC_UTIL_PRF_HMAC = 1, 56 /*! The total number of pseudo-random functions.*/ 57 CC_UTIL_TOTAL_PRFS = 2, 58 /*! Reserved.*/ 59 CC_UTIL_END_OF_PRF_TYPE = 0x7FFFFFFF 60 }mbedtls_util_prftype_t; 61 62 63 /*! 64 @brief This function performs key derivation. 65 66 It is defined as specified in the <em>KDF in Counter Mode</em> section in 67 <em>NIST Special Publication 800-108: Recommendation for Key Derivation 68 Using Pseudorandom Functions</em>. 69 70 The derivation is based on length l, label L, context C, and derivation key 71 Ki. 72 73 AES-CMAC or HMAC are used as the pseudo-random function (PRF). 74 75 @note You must define the label and context for each use-case well 76 when using this API. 77 78 @return \c CC_UTIL_OK on success. 79 @return A non-zero value from cc_util_error.h on failure. 80 */ 81 /* A key-derivation function can iterates n times until l bits of keying material are generated. 82 For each of the iterations of the PRF, i=1 to n, do: 83 result(0) = 0; 84 K(i) = PRF (Ki, [i] || Label || 0x00 || Context || length); 85 results(i) = result(i-1) || K(i); 86 87 concisely, result(i) = K(i) || k(i-1) || .... || k(0)*/ 88 CCUtilError_t mbedtls_util_key_derivation( 89 /*! [in] The key type that is used as an input to a key-derivation 90 function: \p CC_UTIL_USER_KEY or \p CC_UTIL_ROOT_KEY. */ 91 mbedtls_util_keytype_t keyType, 92 /*! [in] A pointer to the key buffer of the user, in case of \p 93 CC_UTIL_USER_KEY. */ 94 mbedtls_util_keydata *pUserKey, 95 /*! [in] The PRF type that is used as an input to a key-derivation 96 function: \p CC_UTIL_PRF_CMAC or \p CC_UTIL_PRF_HMAC. */ 97 mbedtls_util_prftype_t prfType, 98 /*! [in] One of the supported hash modes that are defined in \p 99 CCHashOperationMode_t. */ 100 CCHashOperationMode_t hashMode, 101 /*! [in] A string that identifies the purpose for the derived keying 102 material.*/ 103 const uint8_t *pLabel, 104 /*! [in] The label size must be in range of 1 to 64 bytes in length. */ 105 size_t labelSize, 106 /*! [in] A binary string containing the information related to the derived 107 keying material. */ 108 const uint8_t *pContextData, 109 /*! [in] The context size must be in range of 1 to 64 bytes in length. */ 110 size_t contextSize, 111 /*! [out] Keying material output. Must be at least the size of \p 112 derivedKeySize. */ 113 uint8_t *pDerivedKey, 114 /*! [in] The size of the derived keying material in bytes, up to 4080 115 bytes. */ 116 size_t derivedKeySize 117 ); 118 119 120 /*! 121 @brief This function performs key derivation using using AES-CMAC. 122 123 It is defined as specified in the <em>KDF in Counter Mode</em> section in 124 <em>NIST Special Publication 800-108: Recommendation for Key Derivation 125 Using Pseudorandom Functions</em>. 126 127 The derivation is based on length l, label L, context C, and derivation key 128 Ki. 129 130 @return \c CC_UTIL_OK on success. 131 @return A non-zero value from cc_util_error.h on failure. 132 */ 133 #define mbedtls_util_key_derivation_cmac(keyType, pUserKey, pLabel, labelSize, pContextData, contextSize, pDerivedKey, derivedKeySize) \ 134 mbedtls_util_key_derivation(keyType, pUserKey, CC_UTIL_PRF_CMAC, CC_HASH_OperationModeLast, pLabel, labelSize, pContextData, contextSize, pDerivedKey, derivedKeySize) 135 136 137 /*! 138 @brief This function performs key derivation using HMAC. 139 140 It is defined as specified in the <em>KDF in Counter Mode</em> section in 141 <em>NIST Special Publication 800-108: Recommendation for Key Derivation 142 Using Pseudorandom Functions</em>. 143 144 The derivation is based on length l, label L, context C, and derivation key 145 Ki. 146 147 HMAC is used as the pseudo-random function (PRF). 148 149 @return \c CC_UTIL_OK on success. 150 @return A non-zero value from cc_util_error.h on failure. 151 */ 152 #define mbedtls_util_key_derivation_hmac(keyType, pUserKey, hashMode, pLabel, labelSize, pContextData, contextSize, pDerivedKey, derivedKeySize) \ 153 mbedtls_util_key_derivation(keyType, pUserKey, CC_UTIL_PRF_HMAC, hashMode, pLabel, labelSize, pContextData, contextSize, pDerivedKey, derivedKeySize) 154 155 156 #ifdef __cplusplus 157 } 158 #endif 159 160 /*! 161 @} 162 */ 163 #endif /*_MBEDTLS_CC_UTIL_KEY_DERIVATION_H*/ 164 165
