1 /*--------------------------------------------------------------------------*/ 2 /* Copyright 2020-2021 NXP */ 3 /* */ 4 /* NXP Confidential. This software is owned or controlled by NXP and may */ 5 /* only be used strictly in accordance with the applicable license terms. */ 6 /* By expressly accepting such terms or by downloading, installing, */ 7 /* activating and/or otherwise using the software, you are agreeing that */ 8 /* you have read, and that you agree to comply with and are bound by, such */ 9 /* license terms. If you do not agree to be bound by the applicable license */ 10 /* terms, then you may not retain, install, activate or otherwise use the */ 11 /* software. */ 12 /*--------------------------------------------------------------------------*/ 13 14 /// @file mcuxClCss_Kdf.h 15 /// @brief CSSv2 header for key derivation. 16 /// This header exposes functions that enable using the CSSv2 for various key derivation commands. 17 /// The supported key derivation algorithms are: 18 /// <ul> 19 20 /** 21 * @file mcuxClCss_Kdf.h 22 * @brief CSSv2 header for key derivation. 23 * 24 * This header exposes functions that enable using the CSSv2 for various key derivation commands. 25 * The supported key derivation algorithms are CKDF, HKDF, TLS 26 */ 27 28 29 /** 30 * @defgroup mcuxClCss_Kdf mcuxClCss_Kdf 31 * @brief This part of the @ref mcuxClCss driver supports functionality for key derivation 32 * @ingroup mcuxClCss 33 * @{ 34 */ 35 36 /** 37 * @defgroup mcuxClCss_Kdf_Macros mcuxClCss_Kdf_Macros 38 * @brief Defines all macros of @ref mcuxClCss_Kdf 39 * @ingroup mcuxClCss_Kdf 40 * @{ 41 */ 42 43 44 45 46 47 48 49 #ifndef MCUXCLCSS_KDF_H_ 50 #define MCUXCLCSS_KDF_H_ 51 52 #include <mcuxClCss_Common.h> // Common functionality 53 54 /********************************************** 55 * CONSTANTS 56 **********************************************/ 57 58 /** 59 * @defgroup mcuxClCss_Kdf_Define mcuxClCss_Kdf_Define 60 * @brief constants 61 * @ingroup mcuxClCss_Kdf_Macros 62 * @{ 63 */ 64 65 #define MCUXCLCSS_HKDF_VALUE_RTF_DERIV ((uint32_t) 1u<< 0u) ///< Use RTF as derivation input 66 #define MCUXCLCSS_HKDF_VALUE_MEMORY_DERIV ((uint32_t) 0u<< 0u) ///< Use derivation input from system memory 67 68 #define MCUXCLCSS_CKDF_RTF_DERIV 1U ///< Use RTF as derivation input 69 #define MCUXCLCSS_CKDF_SYSTEM_MEMORY_DERIV 0U ///< Use derivation input from system memory 70 71 #define MCUXCLCSS_CKDF_DERIVATIONDATA_SIZE 12u ///< Size of CKDF derivation data 72 73 #define MCUXCLCSS_CKDF_ALGO_SP800108 0x0u ///< Use SP800-108 algorithm 74 75 #define MCUXCLCSS_HKDF_RFC5869_DERIVATIONDATA_SIZE 32u ///< Size of HKDF derivation data 76 #define MCUXCLCSS_HKDF_SP80056C_TARGETKEY_SIZE 32u ///< Size of HKDF SP800-56C derived key 77 78 #define MCUXCLCSS_HKDF_ALGO_RFC5869 0x0u ///< Use RFC5869 algorithm 79 #define MCUXCLCSS_HKDF_ALGO_SP80056C 0x1u ///< Use SP800-56C algorithm 80 81 82 #define MCUXCLCSS_TLS_DERIVATIONDATA_SIZE ((size_t) 80u) ///< Size of TLS derivation data 83 #define MCUXCLCSS_TLS_RANDOM_SIZE ((size_t) 32u) ///< Size of random bytes for TLS 84 85 #define MCUXCLCSS_TLS_INIT 0u ///< Perform master key generation 86 #define MCUXCLCSS_TLS_FINALIZE 1u ///< Perform session key generation 87 88 /** 89 * @} 90 */ /* MCUXCLCSS_KDF_DEFINE */ 91 92 /********************************************** 93 * TYPEDEFS 94 **********************************************/ 95 96 /** 97 * @defgroup mcuxClCss_Kdf_Types mcuxClCss_Kdf_Types 98 * @brief Defines all types of @ref mcuxClCss_Kdf 99 * @ingroup mcuxClCss_Kdf 100 * @{ 101 */ 102 103 /** Internal command option bit field for CKDF functions. */ 104 typedef union 105 { 106 struct 107 { 108 uint32_t value; ///< Accesses the bit field as a full word; initialize with a combination of constants from @ref MCUXCLCSS_HKDF_VALUE_ 109 } word; 110 struct 111 { 112 uint32_t :12; 113 uint32_t ckdf_algo :2; ///< Defines which algorithm and mode shall be used. This option is set internally and will be ignored: 114 ///< #MCUXCLCSS_CKDF_ALGO_SP800108 = Use SP800-108 algorithm 115 uint32_t :18; 116 } bits; 117 } mcuxClCss_CkdfOption_t; 118 119 /** Command option bit field for #mcuxClCss_Hkdf_Rfc5869_Async. */ 120 typedef union 121 { 122 struct 123 { 124 uint32_t value; ///< Accesses the bit field as a full word; initialize with a combination of constants from @ref MCUXCLCSS_HKDF_VALUE_ 125 } word; 126 struct 127 { 128 uint32_t rtfdrvdat :1; ///< #MCUXCLCSS_CKDF_SYSTEM_MEMORY_DERIV=use derivation input from system memory, #MCUXCLCSS_CKDF_RTF_DERIV=use RTF (runtime fingerprint) as derivation input 129 uint32_t hkdf_algo :1; ///< Defines which algorithm shall be used. This option is set internally and will be ignored: 130 ///< #MCUXCLCSS_HKDF_ALGO_RFC5869 = Use RFC5869 algorithm 131 ///< #MCUXCLCSS_HKDF_ALGO_SP80056C = Use SP800-56C algorithm 132 uint32_t :30; 133 } bits; 134 } mcuxClCss_HkdfOption_t; 135 136 /** Internal command option bit field for #mcuxClCss_TlsGenerateMasterKeyFromPreMasterKey_Async, and #mcuxClCss_TlsGenerateMasterKeyFromPreMasterKey_Async. */ 137 typedef union 138 { 139 struct 140 { 141 uint32_t value; ///< Accesses the bit field as a full word; initialize with a combination of constants from @ref MCUXCLCSS_HKDF_VALUE_ 142 } word; 143 struct 144 { 145 uint32_t :10; 146 uint32_t mode :1; ///< Defines which phase of the key generation is performed. This option is set internally and will be ignored: 147 ///< #MCUXCLCSS_TLS_INIT = Calculate master key from premaster key 148 ///< #MCUXCLCSS_TLS_FINALIZE = Calculate session keys from master key 149 uint32_t :21; 150 } bits; 151 } mcuxClCss_TlsOption_t; 152 153 /** 154 * @} 155 */ /* mcuxClCss_Kdf_Types */ 156 157 /** 158 * @} 159 */ /* mcuxClCss_Kdf_Macros */ 160 161 162 /********************************************** 163 * FUNCTIONS 164 **********************************************/ 165 /** 166 * @defgroup mcuxClCss_Kdf_Functions mcuxClCss_Kdf_Functions 167 * @brief Defines all functions of @ref mcuxClCss_Kdf 168 * @ingroup mcuxClCss_Kdf 169 * @{ 170 */ 171 172 173 /** 174 * @brief Derives a key using the HKDF (HMAC-based key derivation function) according to RFC5869. 175 * It must be ensured that SHA-Direct mode is disabled when calling this function (see #mcuxClCss_ShaDirect_Disable). 176 * Call #mcuxClCss_WaitForOperation to complete the operation. 177 * @param[in] options The command options. For more information, see #mcuxClCss_HkdfOption_t. 178 * @param[in] derivationKeyIdx Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. 179 * @param[in] targetKeyIdx Key bank number of the derived key. Will be a 256-bit key, the user must ensure there is enough space in the keystore to hold the derived key. 180 * @param[in] targetKeyProperties Requested properties for the derived key. The ksize field will be ignored. 181 * @param[in] pDerivationData The algorithm-specific derivation data, the length is #MCUXCLCSS_HKDF_RFC5869_DERIVATIONDATA_SIZE bytes 182 * 183 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 184 * 185 * 186 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 187 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 188 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 189 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_Hkdf_Rfc5869_Async) 190 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Hkdf_Rfc5869_Async( 191 mcuxClCss_HkdfOption_t options, 192 mcuxClCss_KeyIndex_t derivationKeyIdx, 193 mcuxClCss_KeyIndex_t targetKeyIdx, 194 mcuxClCss_KeyProp_t targetKeyProperties, 195 uint8_t const * pDerivationData 196 ); 197 198 /** Derives a key using the HKDF (HMAC-based key derivation function) according to SP800-56C one-step approach with Sha2-256. 199 * It must be ensured that SHA-Direct mode is disabled when calling this function (see #mcuxClCss_ShaDirect_Disable). 200 * Call #mcuxClCss_WaitForOperation to complete the operation. 201 * 202 * @param[in] derivationKeyIdx Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. 203 * @param[out] pTagetKey Memory area to store the derived key. Will be a 256-bit key, the user must ensure there is enough space in the keystore to hold the derived key. 204 * @param[in] pDerivationData The algorithm-specific derivation data 205 * @param[in] derivationDataLength Length of the derivation data 206 * 207 * 208 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 209 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 210 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 211 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 212 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_Hkdf_Sp80056c_Async) 213 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Hkdf_Sp80056c_Async( 214 mcuxClCss_KeyIndex_t derivationKeyIdx, 215 uint8_t * pTagetKey, 216 uint8_t const * pDerivationData, 217 size_t derivationDataLength 218 ); 219 220 221 /** Derives a key using the NIST SP 800-108 CMAC-based Extract-and-Expand Key Derivation Function. 222 * 223 * 224 * Call #mcuxClCss_WaitForOperation to complete the operation. 225 * 226 * @param[in] derivationKeyIdx Key index used for derivation 227 * @param[in] targetKeyIdx Key bank number of the derived key 228 * @param[in] targetKeyProperties Requested properties for the derived key. Only set usage bits. 229 * @param[in] pDerivationData The algorithm-specific derivation data, the length is #MCUXCLCSS_CKDF_DERIVATIONDATA_SIZE bytes 230 * 231 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 232 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 233 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 234 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 235 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_Ckdf_Sp800108_Async) 236 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Ckdf_Sp800108_Async( 237 mcuxClCss_KeyIndex_t derivationKeyIdx, 238 mcuxClCss_KeyIndex_t targetKeyIdx, 239 mcuxClCss_KeyProp_t targetKeyProperties, 240 uint8_t const * pDerivationData 241 ); 242 243 244 245 /** Generates a TLS master key based on a pre-master key and derivation data, according to the TLS 1.2 specification. 246 * The pre-master key is overwritten in this operation. 247 * It must be ensured that SHA-Direct mode is disabled when calling this function (see #mcuxClCss_ShaDirect_Disable). 248 * Call #mcuxClCss_WaitForOperation to complete the operation. 249 * 250 * @param[in] pDerivationData The TLS derivation data, consisting of Label, Client Random and Server Random from the TLS 1.2 specification. 251 * Note: The order is different from #mcuxClCss_TlsGenerateSessionKeysFromMasterKey_Async. 252 * @param[in] keyProperties Desired key properties. Only #mcuxClCss_KeyProp_t::upprot_priv and #mcuxClCss_KeyProp_t::upprot_sec are used, the rest are ignored. 253 * @param[in] keyIdx The index of the TLS pre-master key, which is overwritten with the master key 254 * 255 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 256 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 257 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 258 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 259 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_TlsGenerateMasterKeyFromPreMasterKey_Async) 260 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_TlsGenerateMasterKeyFromPreMasterKey_Async( 261 uint8_t const * pDerivationData, 262 mcuxClCss_KeyProp_t keyProperties, 263 mcuxClCss_KeyIndex_t keyIdx 264 ); 265 266 /** Generates TLS session keys based on a master key and derivation data, according to the TLS 1.2 specification. 267 * The master key and the following five key indices are overwritten in this operation. 268 * The keys are written in the following order: 269 * <ol> 270 * <li> Client Encryption Key 271 * <li> Client Message Authentication Key 272 * <li> Server Encryption Key 273 * <li> Server Message Authentication Key 274 * </ol> 275 * It must be ensured that SHA-Direct mode is disabled when calling this function (see #mcuxClCss_ShaDirect_Disable). 276 * Call #mcuxClCss_WaitForOperation to complete the operation. 277 * 278 * @param[in] pDerivationData The TLS derivation data, consisting of Label, Server Random and Client Random from the TLS 1.2 specification. 279 * Note: The order is different from #mcuxClCss_TlsGenerateMasterKeyFromPreMasterKey_Async. 280 * @param[in] keyProperties Desired key properties. Only #mcuxClCss_KeyProp_t::upprot_priv and #mcuxClCss_KeyProp_t::upprot_sec are used, the rest are ignored. 281 * @param[in] keyIdx The index of the TLS master key, which is overwritten with one of the session keys. 282 * There must be three further consecutive unoccupied key indices following this index. 283 * 284 * @return A code-flow protected error code (see @ref mcuxCsslFlowProtection). The error code can be any error code in @ref MCUXCLCSS_STATUS_, see individual documentation for more information 285 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 286 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 287 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 288 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_TlsGenerateSessionKeysFromMasterKey_Async) 289 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_TlsGenerateSessionKeysFromMasterKey_Async( 290 uint8_t const * pDerivationData, 291 mcuxClCss_KeyProp_t keyProperties, 292 mcuxClCss_KeyIndex_t keyIdx 293 ); 294 295 /** 296 * @} 297 */ /* mcuxClCss_Kdf_Functions */ 298 299 /** 300 * @} 301 */ /* mcuxClCss_Kdf */ 302 303 #endif /* MCUXCLCSS_KDF_H_ */ 304 305
