222 lines
7.6 KiB
C
222 lines
7.6 KiB
C
/*
|
|
* 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 */
|
|
|
|
/**
|
|
@}
|
|
*/
|
|
|