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_management 9 @{ 10 */ 11 12 /*! 13 @file 14 @brief This file contains all CryptoCell Management APIs and definitions. 15 16 The following terms, used throughout this module, are defined in 17 <em>Arm® v8-M Architecture Reference Manual</em>: 18 <ul><li>Privileged and unprivileged modes.</li> 19 <li>Secure and Non-secure modes.</li></ul> 20 */ 21 22 23 24 #ifndef _MBEDTLS_CC_MNG_H 25 #define _MBEDTLS_CC_MNG_H 26 27 /* *********************** Includes ***************************** */ 28 #include "cc_pal_types_plat.h" 29 30 #ifdef __cplusplus 31 extern "C" 32 { 33 #endif 34 35 36 /* *********************** Defines ***************************** */ 37 /* *********************** Macros ***************************** */ 38 39 40 /* *********************** Enums ***************************** */ 41 /*! RMA statuses. */ 42 typedef enum { 43 /*! Non-RMA: bit [30] = 0, bit [31] = 0. */ 44 CC_MNG_NON_RMA = 0, 45 /*! Pending RMA: bit [30] = 1, bit [31] = 0. */ 46 CC_MNG_PENDING_RMA = 1, 47 /*! Illegal state: bit [30] = 0, bit [31] = 1. */ 48 CC_MNG_ILLEGAL_STATE = 2, 49 /*! RMA: bit [30] = 1, bit [31] = 1. */ 50 CC_MNG_RMA = 3, 51 /*! Reserved. */ 52 CC_MNG_END_OF_RMA_STATUS = 0x7FFFFFFF 53 }mbedtls_mng_rmastatus; 54 55 /*! AES HW key types. */ 56 typedef enum { 57 /*! Device root key (HUK). */ 58 CC_MNG_HUK_KEY = 0, 59 /*! Platform key (Krtl). */ 60 CC_MNG_RTL_KEY = 1, 61 /*! ICV provisioning key (Kcp). */ 62 CC_MNG_PROV_KEY = 2, 63 /*! OEM code-encryption key (Kce). */ 64 CC_MNG_CE_KEY = 3, 65 /*! OEM provisioning key (Kpicv). */ 66 CC_MNG_ICV_PROV_KEY = 4, 67 /*! ICV code-encryption key (Kceicv). */ 68 CC_MNG_ICV_CE_KEY = 5, 69 /*! Total number of HW Keys. */ 70 CC_MNG_TOTAL_HW_KEYS = 6, 71 /*! Reserved. */ 72 CC_MNG_END_OF_KEY_TYPE = 0x7FFFFFFF 73 }mbedtls_mng_keytype; 74 75 /*! APB-C only part IDs. */ 76 typedef enum { 77 /*! Secure accesses. */ 78 CC_MNG_APBC_SEC_ID = 0, 79 /*! Privileged accesses. */ 80 CC_MNG_APBC_PRIV_ID = 1, 81 /*! Instruction accesses. */ 82 CC_MNG_APBC_INST_ID = 2, 83 /*! Total part IDs. */ 84 CC_MNG_APBC_TOTAL_ID = 3, 85 /*! Reserved. */ 86 CC_MNG_APBC_END_OF_ID = 0x7FFFFFFF 87 }mbedtls_mng_apbc_parts; 88 89 /*! APB-C part configuration. */ 90 typedef enum { 91 /*! Use APB-C as an input when there is no need to change bits. 92 Modify bit = 0. */ 93 CC_MNG_APBC_NO_CHANGE = 0, 94 /*! Use APB-C as an input when you need to set the 'Allow' bit to '0' and 95 leave this part unlocked. Modify bit = 1, Allow bit = 0, Allow Lock 96 bit = 0. */ 97 CC_MNG_APBC_ALLOW_0_ALLOWLOCK_0 = 1, 98 /*! Use APB-C as an input when you need to set the 'Allow' bit to '0' and 99 lock this part. Modify bit = 1, Allow bit = 0, Allow Lock bit = 1. */ 100 CC_MNG_APBC_ALLOW_0_ALLOWLOCK_1 = 2, 101 /*! Use APB-C as an input when you need to set the 'Allow' bit to '1' and 102 leave this part unlocked. Modify bit = 1, Allow bit = 1, Allow Lock 103 bit = 0. */ 104 CC_MNG_APBC_ALLOW_1_ALLOWLOCK_0 = 3, 105 /*! Use APB-C as an input when you need to set the 'Allow' bit to '1' and 106 lock this part. Modify bit = 1, Allow bit = 1, Allow Lock bit = 1. */ 107 CC_MNG_APBC_ALLOW_1_ALLOWLOCK_1 = 4, 108 /*! Total parts. */ 109 CC_MNG_APBC_TOTAL_PARTS_CONFIG = 5, 110 /*! Reserved. */ 111 CC_MNG_APBC_END_OF_PARTS_CONFIG = 0x7FFFFFFF 112 }mbedtls_mng_apbc_parts_config; 113 114 /************************ Typedefs ****************************/ 115 116 /*! A uint8_t representation for the APB-C parts in the AO_APB_FILTERING 117 register. */ 118 typedef union mbedtls_mng_apbc_part{ 119 /*! A representation of the APB-C value in the AO_APB_FILTERING register.*/ 120 uint8_t apbcPartVal; 121 /*! A representation of the APB-C parts in the AO_APB_FILTERING register.*/ 122 struct { 123 /*! APB-C accepts only 'mbedtls_mng_apbc_parts' accesses. */ 124 uint8_t accessAllow : 1; 125 /*! APB-C \p accessAllow cannot be modified. */ 126 uint8_t accessAllowLock : 1; 127 /*! User decided to modify the upper couple. */ 128 uint8_t accessModify : 1; 129 /*! APB-C part access bits. */ 130 uint8_t rfu : 5; 131 }apbcPartBits; 132 }mbedtls_mng_apbc_part; 133 134 /*! Input to the mbedtls_mng_apbc_config_set() function. */ 135 typedef union mbedtls_mng_apbcconfig{ 136 /*! APB-C configuration values. */ 137 uint32_t apbcConfigVal; 138 /*! An array of the configuration bits for the Secure, Privileged, and 139 Instruction parts. */ 140 mbedtls_mng_apbc_part apbcPart[CC_MNG_APBC_TOTAL_ID + 1]; 141 }mbedtls_mng_apbcconfig; 142 143 144 /* ****************************************** Public Functions **************************************** */ 145 /* 146 Management APIs enable to set, get or obtain device status by reading or writing the 147 appropriate registers or the OTP. 148 */ 149 /* ********************************************************************************************** */ 150 /*! 151 @brief This function reads the OTP word of the OEM flags, 152 and returns the OEM RMA flag status: TRUE or FALSE. 153 154 The function returns the value only in DM LCS or Secure LCS. 155 It validates the device RoT configuration, and returns the 156 value only if both HBK0 and HBK1 are supported. 157 Otherwise, it returns FALSE regardless of the OTP status. 158 159 @return CC_OK on success. 160 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 161 */ 162 int mbedtls_mng_pending_rma_status_get( 163 /*! [out] The RMA status. */ 164 uint32_t *rmaStatus 165 ); 166 167 /*! 168 @brief This function verifies and returns the CryptoCell HW version. 169 170 @return CC_OK on success. 171 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 172 */ 173 int mbedtls_mng_hw_version_get( 174 /*! [out] The part number. */ 175 uint32_t *partNumber, 176 /*! [out] The HW version. */ 177 uint32_t *revision 178 ); 179 180 /*! 181 @brief This function sets CryptoCell to Secured mode. 182 183 Setting CryptoCell to Secured mode can only be done while CryptoCell is idle. 184 185 @return CC_OK on success. 186 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 187 */ 188 int mbedtls_mng_cc_sec_mode_set( 189 /*! [in] True: Set CryptoCell to Secured mode. False: Set CryptoCell 190 to non-Secured mode. */ 191 CCBool_t isSecAccessMode, 192 /*! [in] True: Lock CryptoCell to current mode. False: Do not lock 193 CryptoCell to current mode. Allows calling this function again. */ 194 CCBool_t isSecModeLock 195 ); 196 197 /*! 198 @brief This function sets CryptoCell to Privileged mode. 199 200 Setting CryptoCell to Privileged mode can only be done while CryptoCell is idle. 201 202 @return CC_OK on success. 203 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 204 */ 205 int mbedtls_mng_cc_priv_mode_set( 206 /*! [in] True: Set CryptoCell to privileged mode. False: Set 207 CryptoCell to unprivileged mode. */ 208 CCBool_t isPrivAccessMode, 209 /*! [in] True: Lock CryptoCell to current mode. False: Do not lock 210 CryptoCell to current mode. Allows calling this function again. */ 211 CCBool_t isPrivModeLock 212 ); 213 214 /*! 215 @brief This function sets the shadow register of one of the 216 HW Keys when the device is in CM LCS or DM LCS. 217 218 @return CC_OK on success. 219 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 220 */ 221 int mbedtls_mng_debug_key_set( 222 /*! [in] The type of the HW key. One of the following values: HUK, 223 Kcp, Kce, Kpicv, or Kceicv. */ 224 mbedtls_mng_keytype keyType, 225 /*! [in] A pointer to the buffer holding the HW key. */ 226 uint32_t *pHwKey, 227 /*! [in] The size of the HW key in bytes. */ 228 size_t keySize 229 ); 230 231 /*! 232 @brief This function retrieves the general configuration from the OTP. 233 See <em>Arm CryptoCell-312 Software Integrators Manual</em>. 234 235 @return CC_OK on success. 236 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 237 */ 238 int mbedtls_mng_gen_config_get( 239 /*! [out] The OTP configuration word. */ 240 uint32_t *pOtpWord 241 ); 242 243 /*! 244 @brief This function locks the usage of either Kcp, Kce, or both during runtime, 245 in either Secure LCS or RMA LCS. 246 247 @return CC_OK on success. 248 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 249 */ 250 int mbedtls_mng_oem_key_lock( 251 /*! [in] The flag for locking Kcp usage. */ 252 CCBool_t kcpLock, 253 /*! [in] The flag for locking Kce usage. */ 254 CCBool_t kceLock 255 ); 256 257 /*! 258 @brief This function sets CryptoCell APB-C into one of the following modes: 259 Secured access mode, Privileged access mode, or Instruction access 260 mode. 261 262 @return CC_OK on success. 263 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 264 */ 265 int mbedtls_mng_apbc_config_set( 266 /*! Secured access mode. */ 267 mbedtls_mng_apbc_parts_config securePartCfg, 268 /*! Privileged access mode.*/ 269 mbedtls_mng_apbc_parts_config privPartCfg, 270 /*! Instruction access mode. */ 271 mbedtls_mng_apbc_parts_config instPartCfg 272 ); 273 /*! 274 @brief This function requests usage of, or releases, the APB-C. 275 276 @note This function must be called before and after each use of APB-C. 277 278 @return CC_OK on success. 279 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 280 */ 281 int mbedtls_mng_apbc_access( 282 /*! [in] TRUE: Request usage of APB-C. FALSE: Free APB-C. */ 283 CCBool_t isApbcAccessUsed 284 ); 285 286 /*! 287 @brief This function is called once the external PMU decides to power-down 288 CryptoCell. 289 290 @return CC_OK on success. 291 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 292 */ 293 int mbedtls_mng_suspend( 294 /*! [in] A pointer to a buffer that can be used for backup. */ 295 uint8_t *pBackupBuffer, 296 /*! [in] The size of the backup buffer. Must be at least 297 \c CC_MNG_MIN_BACKUP_SIZE_IN_BYTES. */ 298 size_t backupSize 299 ); 300 301 /*! 302 @brief This function is called once the external PMU decides to power-up 303 CryptoCell. 304 305 @return CC_OK on success. 306 @return A non-zero value from mbedtls_cc_mng_error.h on failure. 307 */ 308 int mbedtls_mng_resume( 309 /*! [in] A pointer to a buffer that can be used for backup. */ 310 uint8_t *pBackupBuffer, 311 /*! [in] The size of the backup buffer. Must be at least 312 \c CC_MNG_MIN_BACKUP_SIZE_IN_BYTES. */ 313 size_t backupSize 314 ); 315 #ifdef __cplusplus 316 } 317 #endif 318 319 /*! 320 @} 321 */ 322 #endif // _MBEDTLS_CC_MNG_H 323 324
