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 /** 15 * @file mcuxClCss_KeyManagement.h 16 * @brief CSSv2 header for key management. 17 * 18 * This header exposes functions that can be used to manage the keystore of CSSv2. 19 * This includes: 20 * - Importing keys 21 * - Exporting keys 22 * - Deleting keys 23 */ 24 25 /** 26 * @defgroup mcuxClCss_KeyManagement mcuxClCss_KeyManagement 27 * @brief This part of the @ref mcuxClCss driver supports functionality for keys management 28 * @ingroup mcuxClCss 29 * @{ 30 */ 31 32 #ifndef MCUXCLCSS_KEYMANAGEMENT_H_ 33 #define MCUXCLCSS_KEYMANAGEMENT_H_ 34 35 #include <mcuxClCss_Common.h> // Common functionality 36 37 /********************************************** 38 * CONSTANTS 39 **********************************************/ 40 /** 41 * @defgroup mcuxClCss_KeyManagement_Macros mcuxClCss_KeyManagement_Macros 42 * @brief Defines all macros of @ref mcuxClCss_KeyManagement 43 * @ingroup mcuxClCss_KeyManagement 44 * @{ 45 */ 46 47 /** 48 * @defgroup MCUXCLCSS_KEYIMPORT_VALUE_KFMT_ MCUXCLCSS_KEYIMPORT_VALUE_KFMT_ 49 * @brief Defines valid options (word value) to be used by #mcuxClCss_KeyImport_Async 50 * @ingroup mcuxClCss_KeyManagement_Macros 51 * 52 * @{ 53 */ 54 55 #define MCUXCLCSS_KEYIMPORT_VALUE_KFMT_UDF ((uint32_t) 0u<< 6u) ///< Key format UDF with shares in RTL or memory 56 #define MCUXCLCSS_KEYIMPORT_VALUE_KFMT_RFC3394 ((uint32_t) 1u<< 6u) ///< Key format RFC3394 with shares in memory 57 #define MCUXCLCSS_KEYIMPORT_VALUE_KFMT_PUF ((uint32_t) 2u<< 6u) ///< Key from PUF 58 59 /** 60 * @} 61 */ 62 63 /** 64 * @defgroup MCUXCLCSS_KEYIMPORT_KFMT_ MCUXCLCSS_KEYIMPORT_KFMT_ 65 * @brief Defines valid options (bit values) to be used by #mcuxClCss_KeyImport_Async 66 * @ingroup mcuxClCss_KeyManagement_Macros 67 * 68 * @{ 69 */ 70 #define MCUXCLCSS_KEYIMPORT_KFMT_UDF ((uint32_t) 0x00u) ///< Key format UDF with shares in RTL or memory 71 #define MCUXCLCSS_KEYIMPORT_KFMT_RFC3394 ((uint32_t) 0x01u) ///< Key format RFC3394 with shares in memory 72 #define MCUXCLCSS_KEYIMPORT_KFMT_PUF ((uint32_t) 0x02u) ///< Key from PUF 73 74 #define MCUXCLCSS_RFC3394_OVERHEAD ((size_t) 16u) ///< Overhead between RFC3394 blob and key size 75 /** 76 * @} 77 */ 78 79 /** 80 * @defgroup MCUXCLCSS_RFC3394_ MCUXCLCSS_RFC3394_ 81 * @brief Defines specifying the length of RFC3394 containers 82 * @ingroup mcuxClCss_KeyManagement_Macros 83 * 84 * @{ 85 */ 86 #define MCUXCLCSS_RFC3394_CONTAINER_SIZE_128 ((size_t) 256u/8u) ///< Size of RFC3394 container for 128 bit key 87 #define MCUXCLCSS_RFC3394_CONTAINER_SIZE_256 ((size_t) 384u/8u) ///< Size of RFC3394 container for 256 bit key 88 /** 89 * @} 90 */ 91 92 /** 93 * @} 94 */ 95 96 /********************************************** 97 * TYPEDEFS 98 **********************************************/ 99 /** 100 * @defgroup mcuxClCss_KeyManagement_Types mcuxClCss_KeyManagement_Types 101 * @brief Defines all types of @ref mcuxClCss_KeyManagement 102 * @ingroup mcuxClCss_KeyManagement 103 * @{ 104 */ 105 106 /** 107 * @brief Command option bit field for #mcuxClCss_KeyImport_Async 108 * 109 * Bit field to configure #mcuxClCss_KeyImport_Async. 110 * See @ref MCUXCLCSS_KEYIMPORT_KFMT_ for possible options in case the struct is accessed bit-wise. 111 * See @ref MCUXCLCSS_KEYIMPORT_VALUE_KFMT_ for possible options in case the struct is accessed word-wise. 112 */ 113 typedef union 114 { 115 struct 116 { 117 uint32_t value; ///< Accesses the bit field as a full word; initialize with a combination of constants from @ref MCUXCLCSS_KEYIMPORT_VALUE_KFMT_ 118 } word; ///< Access #mcuxClCss_KeyImportOption_t word-wise 119 struct 120 { 121 uint32_t :4; ///< RFU 122 uint32_t revf :1; ///< This field is managed internally 123 uint32_t :1; ///< RFU 124 uint32_t kfmt :2; ///< Defines the key import format, one of @ref MCUXCLCSS_KEYIMPORT_KFMT_ 125 uint32_t :24; ///< RFU 126 } bits; ///< Access #mcuxClCss_KeyImportOption_t bit-wise 127 } mcuxClCss_KeyImportOption_t; 128 129 /** 130 * @} 131 */ 132 133 /********************************************** 134 * FUNCTIONS 135 **********************************************/ 136 /** 137 * @defgroup mcuxClCss_KeyManagement_Functions mcuxClCss_KeyManagement_Functions 138 * @brief Defines all functions of @ref mcuxClCss_KeyManagement 139 * @ingroup mcuxClCss_KeyManagement 140 * @{ 141 */ 142 143 /** 144 * @brief Deletes a key from keystore at the given index. 145 * 146 * Before execution, CSS will wait until #mcuxClCss_HwState_t.drbgentlvl == #MCUXCLCSS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call. 147 * 148 * Call #mcuxClCss_WaitForOperation to complete the operation. 149 * 150 * @param[in] keyIdx The index of the key to be deleted 151 * 152 * @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 153 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 154 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 155 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 156 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_KeyDelete_Async) 157 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_KeyDelete_Async( 158 mcuxClCss_KeyIndex_t keyIdx 159 ); 160 161 162 163 /** @brief Imports a key from external storage to an internal key register. 164 * 165 * 166 * Call #mcuxClCss_WaitForOperation to complete the operation. 167 * 168 * @param[in] options One of @ref MCUXCLCSS_KEYIMPORT_KFMT_ 169 * @param[in] pImportKey Pointer to the RFC3394 container of the key to be imported 170 * @param[in] importKeyLength Length of the RFC3394 container of the key to be imported 171 * @param[in] wrappingKeyIdx Index of the key wrapping key, if importing RFC3394 format 172 * @param[in] targetKeyIdx The desired key index of the imported key 173 * 174 * <dl> 175 * <dt>Parameter properties</dt> 176 * <dd><dl> 177 * <dt>@p options.kfmt != #MCUXCLCSS_KEYIMPORT_KFMT_RFC3394</dt><dd> 178 * <ul style="list-style: none;"> 179 * <li>@p pImportKey is ignored.</li> 180 * <li>@p importKeyLength is ignored.</li> 181 * <li>@p wrappingKeyIdx is ignored.</li> 182 * <li>@p targetKeyIdx is ignored. The unpacked key is automatically stored in key slots 0, 1.</li> 183 * </ul></dd> 184 * </dt> 185 * </dl></dd> 186 * </dl> 187 * 188 * @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 189 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 190 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 191 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 192 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_KeyImport_Async) 193 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_KeyImport_Async( 194 mcuxClCss_KeyImportOption_t options, 195 uint8_t const * pImportKey, 196 size_t importKeyLength, 197 mcuxClCss_KeyIndex_t wrappingKeyIdx, 198 mcuxClCss_KeyIndex_t targetKeyIdx 199 ); 200 201 202 /** @brief Exports a key from an internal key register to external storage, using a wrapping key. 203 * 204 * 205 * Call #mcuxClCss_WaitForOperation to complete the operation. 206 * 207 * @param[in] wrappingKeyIdx The key used for key wrapping 208 * @param[in] exportKeyIdx The key to export 209 * @param[out] pOutput The memory address of the exported key 210 * 211 * @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 212 * @retval #MCUXCLCSS_STATUS_SW_INVALID_PARAM if invalid parameters were specified 213 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 214 * @retval #MCUXCLCSS_STATUS_OK_WAIT on successful request */ 215 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_KeyExport_Async) 216 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_KeyExport_Async( 217 mcuxClCss_KeyIndex_t wrappingKeyIdx, ///< [in] The key used for key wrapping 218 mcuxClCss_KeyIndex_t exportKeyIdx, ///< [in] The key to export 219 uint8_t * pOutput ///< [out] The memory address of the exported key 220 ); 221 222 /** @brief Exports the properties of the keys stored in the CSS internal keystore 223 * 224 * Call #mcuxClCss_WaitForOperation to complete the operation. 225 * 226 * @param[in] keyIdx Request key properties of the index defined here 227 * @param[out] pKeyProp Key properties of the index provided 228 * 229 * @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 230 * @retval #MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT if a running operation prevented the request 231 * @retval #MCUXCLCSS_STATUS_OK on successful request */ 232 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClCss_GetKeyProperties) 233 MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_GetKeyProperties( 234 mcuxClCss_KeyIndex_t keyIdx, 235 mcuxClCss_KeyProp_t * pKeyProp 236 ); 237 238 /** 239 * @} 240 */ 241 #endif /* MCUXCLCSS_KEYMANAGEMENT_H_ */ 242 243 /** 244 * @} 245 */ 246
