diff options
Diffstat (limited to 'include/drivers/arm/cryptocell/713/bsv_api.h')
| -rw-r--r-- | include/drivers/arm/cryptocell/713/bsv_api.h | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/include/drivers/arm/cryptocell/713/bsv_api.h b/include/drivers/arm/cryptocell/713/bsv_api.h new file mode 100644 index 0000000..dc49473 --- /dev/null +++ b/include/drivers/arm/cryptocell/713/bsv_api.h @@ -0,0 +1,221 @@ +/* + * Copyright (c) 2017-2020 ARM Limited and Contributors. All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef _BSV_API_H +#define _BSV_API_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +/*! +@file +@brief This file contains the Boot Services APIs and definitions. + +@defgroup cc_bsv_api CryptoCell Boot Services APIs and definitions +@{ +@ingroup cc_bsv +*/ + +#include "cc_pal_types.h" +#include "cc_sec_defs.h" +#include "cc_boot_defs.h" + +/* Life cycle state definitions. */ +#define CC_BSV_CHIP_MANUFACTURE_LCS 0x0 /*!< The CM life-cycle state (LCS) value. */ +#define CC_BSV_DEVICE_MANUFACTURE_LCS 0x1 /*!< The DM life-cycle state (LCS) value. */ +#define CC_BSV_SECURE_LCS 0x5 /*!< The Secure life-cycle state (LCS) value. */ +#define CC_BSV_RMA_LCS 0x7 /*!< The RMA life-cycle state (LCS) value. */ +#define CC_BSV_INVALID_LCS 0xff /*!< The invalid life-cycle state (LCS) value. */ + +/*---------------------------- + TYPES +-----------------------------------*/ + +/*---------------------------- + PUBLIC FUNCTIONS +-----------------------------------*/ + + +/*! +@brief This function verifies the product and version numbers of the HW, and initializes it. + +\warning This function must be the first CryptoCell-7xx SBROM library API called. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvInit( + unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ + ); + +/*! +@brief This function retrieves the HW LCS and performs validity checks. + +If the LCS is RMA, it also sets the OTP secret keys to a fixed value. + +@note An error is returned if there is an invalid LCS. If this happens, your code must +completely disable the device. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvGetAndInitLcs( + unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ + uint32_t *pLcs /*!< [out] The value of the current LCS. */ + ); + +/*! +@brief This function retrieves the LCS from the NVM manager. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvLcsGet( + unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ + uint32_t *pLcs /*!< [out] The value of the current LCS. */ + ); + +/*! +@brief This function reads software revocation counter from OTP memory, according to the provided sw version index. +SW version is stored in NVM counter and represented by ones. Meaning seVersion=5 would be stored as binary 0b11111; +hence: + the maximal of trusted is 32 + the maximal of non-trusted is 224 + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvSwVersionGet( + unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ + CCSbSwVersionId_t id, /*!< [in] Enumeration defining the trusted/non-trusted counter to read. */ + uint32_t *swVersion /*!< [out] The value of the requested counter as read from OTP memory. */ + ); + +/*! +@brief This function sets the NVM counter according to swVersionID (trusted/non-trusted). + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvSwVersionSet( + unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ + CCSbSwVersionId_t id, /*!< [in] Enumeration defining the trusted/non-trusted counter to read. */ + uint32_t swVersion /*!< [in] New value of the counter to be programmed in OTP memory. */ + ); + +/*! +@brief This function sets the "fatal error" flag in the NVM manager, to disable the use of +any HW keys or security services. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvFatalErrorSet( + unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ + ); + +/*! +@brief This function retrieves the public key hash from OTP memory, according to the provided index. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvPubKeyHashGet( + unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ + CCSbPubKeyIndexType_t keyIndex, /*!< [in] Enumeration defining the key hash to retrieve: 128-bit HBK0, 128-bit HBK1, or 256-bit HBK. */ + uint32_t *hashedPubKey, /*!< [out] A buffer to contain the public key HASH. */ + uint32_t hashResultSizeWords /*!< [in] The size of the hash in 32-bit words: + - Must be 4 for 128-bit hash. + - Must be 8 for 256bit hash. */ + ); + +/*! +@brief This function permanently sets the RMA LCS for the ICV and the OEM. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvRMAModeEnable( + unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ + ); + +/*! +@brief This function is called by the ICV code, to disable the OEM code from changing the ICV RMA bit flag. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvICVRMAFlagBitLock( + unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ + ); + +/*! +@brief This function locks the defined ICV class keys from further usage. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvICVKeyLock( + unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ + CCBool_t isICVProvisioningKeyLock, /*!< [in] Should the provisioning key be locked. */ + CCBool_t isICVCodeEncKeyLock /*!< [in] Should the encryption key be locked. */ + ); + + +/*! +@brief This function retrieves the value of "secure disable" bit. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvSecureDisableGet( + unsigned long hwBaseAddress, /*!< [in] HW registers base address. */ + CCBool_t *isSDEnabled /*!< [out] The value of the SD Enable bit. */ + ); + + +/*! +@brief This function derives the platform key (Kplt) from the Kpicv, and then decrypts the customer key (Kcst) +from the EKcst (burned in the OTP). The decryption is done only in Secure and RMA LCS mode using AES-ECB. +The customer ROM should invoke this function during early boot, prior to running any non-ROM code, only if Kcst exists. +The resulting Kcst is saved in a HW register. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvCustomerKeyDecrypt( + unsigned long hwBaseAddress /*!< [in] The base address of the CryptoCell HW registers. */ + ); +#ifdef __cplusplus +} +#endif + +/*! +@brief This function derives the unique SoC_ID for the device, as hashed (Hbk || AES_CMAC (HUK)). + +@note SoC_ID is required to create debug certificates. + +The OEM or ICV must provide a method for a developer to discover the SoC_ID of a target +device without having to first enable debugging. +One suggested implementation is to have the device ROM code compute the SoC_ID and place +it in a specific location in the flash memory, from where it can be accessed by the developer. + +@return \c CC_OK on success. +@return A non-zero value from bsv_error.h on failure. +*/ +CCError_t CC_BsvSocIDCompute( + unsigned long hwBaseAddress, /*!< [in] The base address of the CryptoCell HW registers. */ + CCHashResult_t hashResult /*!< [out] The derived SoC_ID. */ + ); + +#endif /* _BSV_API_H */ + +/** +@} + */ + |