1 /* 2 * Copyright (c) 2017-2020 ARM Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _BSV_API_H 8 #define _BSV_API_H 9 10 #ifdef __cplusplus 11 extern "C" 12 { 13 #endif 14 15 /*! 16 @file 17 @brief This file contains the Boot Services APIs and definitions. 18 19 @defgroup cc_bsv_api CryptoCell Boot Services APIs and definitions 20 @{ 21 @ingroup cc_bsv 22 */ 23 24 #include "cc_pal_types.h" 25 #include "cc_sec_defs.h" 26 #include "cc_boot_defs.h" 27 28 /* Life cycle state definitions. */ 29 #define CC_BSV_CHIP_MANUFACTURE_LCS 0x0 /*!< The CM life-cycle state (LCS) value. */ 30 #define CC_BSV_DEVICE_MANUFACTURE_LCS 0x1 /*!< The DM life-cycle state (LCS) value. */ 31 #define CC_BSV_SECURE_LCS 0x5 /*!< The Secure life-cycle state (LCS) value. */ 32 #define CC_BSV_RMA_LCS 0x7 /*!< The RMA life-cycle state (LCS) value. */ 33 #define CC_BSV_INVALID_LCS 0xff /*!< The invalid life-cycle state (LCS) value. */ 34 35 /*---------------------------- 36 TYPES 37 -----------------------------------*/ 38 39 /*---------------------------- 40 PUBLIC FUNCTIONS 41 -----------------------------------*/ 42 43 44 /*! 45 @brief This function verifies the product and version numbers of the HW, and initializes it. 46 47 \warning This function must be the first CryptoCell-7xx SBROM library API called. 48 49 @return \c CC_OK on success. 50 @return A non-zero value from bsv_error.h on failure. 51 */ 52 CCError_t CC_BsvInit( 53 unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ 54 ); 55 56 /*! 57 @brief This function retrieves the HW LCS and performs validity checks. 58 59 If the LCS is RMA, it also sets the OTP secret keys to a fixed value. 60 61 @note An error is returned if there is an invalid LCS. If this happens, your code must 62 completely disable the device. 63 64 @return \c CC_OK on success. 65 @return A non-zero value from bsv_error.h on failure. 66 */ 67 CCError_t CC_BsvGetAndInitLcs( 68 unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ 69 uint32_t *pLcs /*!< [out] The value of the current LCS. */ 70 ); 71 72 /*! 73 @brief This function retrieves the LCS from the NVM manager. 74 75 @return \c CC_OK on success. 76 @return A non-zero value from bsv_error.h on failure. 77 */ 78 CCError_t CC_BsvLcsGet( 79 unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ 80 uint32_t *pLcs /*!< [out] The value of the current LCS. */ 81 ); 82 83 /*! 84 @brief This function reads software revocation counter from OTP memory, according to the provided sw version index. 85 SW version is stored in NVM counter and represented by ones. Meaning seVersion=5 would be stored as binary 0b11111; 86 hence: 87 the maximal of trusted is 32 88 the maximal of non-trusted is 224 89 90 @return \c CC_OK on success. 91 @return A non-zero value from bsv_error.h on failure. 92 */ 93 CCError_t CC_BsvSwVersionGet( 94 unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ 95 CCSbSwVersionId_t id, /*!< [in] Enumeration defining the trusted/non-trusted counter to read. */ 96 uint32_t *swVersion /*!< [out] The value of the requested counter as read from OTP memory. */ 97 ); 98 99 /*! 100 @brief This function sets the NVM counter according to swVersionID (trusted/non-trusted). 101 102 @return \c CC_OK on success. 103 @return A non-zero value from bsv_error.h on failure. 104 */ 105 CCError_t CC_BsvSwVersionSet( 106 unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ 107 CCSbSwVersionId_t id, /*!< [in] Enumeration defining the trusted/non-trusted counter to read. */ 108 uint32_t swVersion /*!< [in] New value of the counter to be programmed in OTP memory. */ 109 ); 110 111 /*! 112 @brief This function sets the "fatal error" flag in the NVM manager, to disable the use of 113 any HW keys or security services. 114 115 @return \c CC_OK on success. 116 @return A non-zero value from bsv_error.h on failure. 117 */ 118 CCError_t CC_BsvFatalErrorSet( 119 unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ 120 ); 121 122 /*! 123 @brief This function retrieves the public key hash from OTP memory, according to the provided index. 124 125 @return \c CC_OK on success. 126 @return A non-zero value from bsv_error.h on failure. 127 */ 128 CCError_t CC_BsvPubKeyHashGet( 129 unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ 130 CCSbPubKeyIndexType_t keyIndex, /*!< [in] Enumeration defining the key hash to retrieve: 128-bit HBK0, 128-bit HBK1, or 256-bit HBK. */ 131 uint32_t *hashedPubKey, /*!< [out] A buffer to contain the public key HASH. */ 132 uint32_t hashResultSizeWords /*!< [in] The size of the hash in 32-bit words: 133 - Must be 4 for 128-bit hash. 134 - Must be 8 for 256bit hash. */ 135 ); 136 137 /*! 138 @brief This function permanently sets the RMA LCS for the ICV and the OEM. 139 140 @return \c CC_OK on success. 141 @return A non-zero value from bsv_error.h on failure. 142 */ 143 CCError_t CC_BsvRMAModeEnable( 144 unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ 145 ); 146 147 /*! 148 @brief This function is called by the ICV code, to disable the OEM code from changing the ICV RMA bit flag. 149 150 @return \c CC_OK on success. 151 @return A non-zero value from bsv_error.h on failure. 152 */ 153 CCError_t CC_BsvICVRMAFlagBitLock( 154 unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ 155 ); 156 157 /*! 158 @brief This function locks the defined ICV class keys from further usage. 159 160 @return \c CC_OK on success. 161 @return A non-zero value from bsv_error.h on failure. 162 */ 163 CCError_t CC_BsvICVKeyLock( 164 unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ 165 CCBool_t isICVProvisioningKeyLock, /*!< [in] Should the provisioning key be locked. */ 166 CCBool_t isICVCodeEncKeyLock /*!< [in] Should the encryption key be locked. */ 167 ); 168 169 170 /*! 171 @brief This function retrieves the value of "secure disable" bit. 172 173 @return \c CC_OK on success. 174 @return A non-zero value from bsv_error.h on failure. 175 */ 176 CCError_t CC_BsvSecureDisableGet( 177 unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ 178 CCBool_t *isSDEnabled /*!< [out] The value of the SD Enable bit. */ 179 ); 180 181 182 /*! 183 @brief This function derives the platform key (Kplt) from the Kpicv, and then decrypts the customer key (Kcst) 184 from the EKcst (burned in the OTP). The decryption is done only in Secure and RMA LCS mode using AES-ECB. 185 The customer ROM should invoke this function during early boot, prior to running any non-ROM code, only if Kcst exists. 186 The resulting Kcst is saved in a HW register. 187 188 @return \c CC_OK on success. 189 @return A non-zero value from bsv_error.h on failure. 190 */ 191 CCError_t CC_BsvCustomerKeyDecrypt( 192 unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ 193 ); 194 #ifdef __cplusplus 195 } 196 #endif 197 198 /*! 199 @brief This function derives the unique SoC_ID for the device, as hashed (Hbk || AES_CMAC (HUK)). 200 201 @note SoC_ID is required to create debug certificates. 202 203 The OEM or ICV must provide a method for a developer to discover the SoC_ID of a target 204 device without having to first enable debugging. 205 One suggested implementation is to have the device ROM code compute the SoC_ID and place 206 it in a specific location in the flash memory, from where it can be accessed by the developer. 207 208 @return \c CC_OK on success. 209 @return A non-zero value from bsv_error.h on failure. 210 */ 211 CCError_t CC_BsvSocIDCompute( 212 unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ 213 CCHashResult_t hashResult /*!< [out] The derived SoC_ID. */ 214 ); 215 216 #endif /* _BSV_API_H */ 217 218 /** 219 @} 220 */ 221 222