Trusted Firmware-M (TF-M)¶
The CC27xx implements the Trust Firmware-M (TF-M) version 2.0 for the Secure Processing Environment (SPE). Additional documentation may be found here. The SimpleLink Software Development kit ships with a pre-built TF-M image. However, rebuilding is supported to allow for customization of the image.
Configuring TF-M¶
the CC27xx TF-M configurability options such as Cryptographic algorithm support and Key Storage parameters may be found in <SDK>/tfm_s/cc27xx/production_full/config/config_tfm_project.h. The config_tfm_project.h header contains documentation and guidance for configuring the various options.
The memory addresses of the Secure (S) and Non-Secure (NS) regions can be modified by editing <SDK>/tfm_s/cc27xx/production_full/memory_layout.yml.
If the NS_ROM_BASE address is modified, the linker files used to build the NS application must be modified accordingly to set the correct flash-base address and size. The linker files (cc27xx*_ns.*) for all compilers are located in either <SDK>/source/ti/boards/cc27xxx10 or <SDK>/source/ti/boards/cc27xxx20, depending on the device memory variant. Similarly, if secure boot is enabled, the Primary Secure and Non-Secure start addresses and length will need to be updated in SysConfig.
If the “S_ROM_BASE” address is modified, the VTOR must be updated:
If secure boot is disabled, then the VTOR address can be updated in SysConfig under TI DEVICES –> Device Configuration –> Boot Configuration –> Application Vector Table. This should be to “S_ROM_BASE” + 0x100 for the BL2 header.
If secure boot is enabled, then the Primary Secure “Start” address should be updated to match the “S_ROM_BASE” value. This is controlled via SysConfig under TI DEVICES –> Device Configuration –> Security Configuration –> Primary Secure. Additionally, “romFixed” in <SDK Root>/tfm_s/cc27xx/production_full/secure_boot/ti_secure_boot_properties_tfm.json must be set to the value of “S_ROM_BASE” + 0x100.
Building TF-M¶
To install the prerequisites tools to build TF-M, go to the <SDK>/source/third_party/trusted-firmware-m folder and run the following:
1pip3 install -r tools/requirements.txt
To build the TF-M image, go to the <SDK>/tfm_s/cc27xx folder and run the following:
1make clean
2make all
Attestation¶
Attestation is the evidence of the device’s properties, including the identity and lifecycle security state of the device. It mitigates impersonation threats using a cryptographic proof of identity. The combination of an attestation certificate and token provides both static proof (device identity via certificate) and dynamic proof (current state via token) of the device’s trustworthiness. The CC27xx supports attestation according to PSA Certified Attestation API 1.0 with attestation token claims according to PSA_IOT_PROFILE_1 profile.
Attestation Token¶
The attestation token is a signed data structure that is generated dynamically by the device and contains claims about the device’s current state.
This data structure contains:
Boot Seed
HW/ROM Version
Unique HW ID
Security Lifecycle
Software Measurements or Configuration Data
Signature generated using the private key corresponding to the public key in the attestation certificate
For more information, see the What is an entity attestation token page.
Token Claims¶
The following table shows the token claims for PSA_IOT_PROFILE_1 profile. All mandatory claims are supported.
Claim |
Mandatory |
Description |
Notes |
|---|---|---|---|
Auth Challenge |
Yes |
Input object from the caller. For example, this can be a cryptograhpic nonce or a hash of locally attested data. The length must be 32, 48, or 64 bytes. |
|
Instance ID |
Yes |
Represents the unique identifier of the instance. It is a hash of the public key corresponding to the Initial Attestation Key (IAK). If the IAK is a symmetric key then the Instance ID is a hash of the IAK. The full definition is in the PSA-SM. |
|
Verification Service Indicator |
No |
The value is a text string that can be used to locate the service or a URL specifying the address of the service. |
|
Profile Definition |
No |
Contains the name of a document that describes the ‘profile’ of the report. The document name may include versioning. |
Value is PSA_IOT_PROFILE_1 |
Implementation ID |
Yes |
Uniquely identifies the underlying immutable PSA RoT. A verification service can use this claim to locate the details of the verification process. Such details include the implementation’s origin and associated certification state. The full definition is in the PSA-SM. |
FCFG data will be used to generate the implementation ID:
|
Client ID |
Yes |
The Client ID represents the security domain of the caller. In PSA, a security domain is represented by a signed integer whereby negative values represent callers from the NSPE and where positive IDs represent callers from the SPE. The value 0 is not permitted. |
Value is -1 when the token is requested by NSPE. |
Security Lifecycle |
Yes |
Represents the current lifecycle state of the PSA RoT. The state is represented by an integer that is divided to convey a major state and a minor state. A major state is mandatory and defined by the PSA-SM. A minor state is optional and IMPLEMENTATION DEFINED. The PSA security lifecycle state and implementation state are encoded as follows:
|
Lifecycle is dynamically determined based on debug authorization register settings. only the following lifecycle states are attestable:
|
Certification Reference (HW Version) |
No |
Globally unique number in identifying GDSII that went to fabrication, HW and ROM. It can be used to reference the security level of the PSA-ROT via a certification website. The Certification Reference claim is used to link the class of chip and PSA RoT of the attesting device to an associated entry in the PSA Certification database. Format is EAN-13 per the specification. |
|
Boot Seed |
Yes |
Represents a random value created at system boot time that can allow differentiation of of reports from different boot sessions. |
When secure boot is enabled, CC27xx boot ROM writes a new random seed value to Secure RAM at every boot which is used to populate this claim. |
Software Components |
Yes (see note) |
A list of software components that represent all the software loaded by the PSA Root Of Trust. This claim must be included to be conformant with PSA-SM. Each entry has the following fields:
This claim is required to be compliant with the PSA-SM. |
This claim is not supported since the CC27xx boot ROM does not support measuring SW components. |
No SW Measurements |
Yes (see note) |
In the event that the implementation does not contain any software measurements then the Software Components claim above can be omitted but instead it is mandatory to include this claim to indicate this is a deliberate state. This claim is intended for devices that are not compliant with the PSA-SM. |
This claim is included since the SW Components claim is not supported. |
Note
The Software Components claim is mandatory unless the No Software Measurements claim is specified. Otherwise the No Software Measurements claim is mandatory.
Security Lifecycle¶
The security lifecycle state is determined according to the following activity diagram whenever the token is requested.
Figure 82. Security Lifecycle Diagram.¶
Attestation Key¶
ECDSA is used to sign the attestation token. The attestation key may be pre-provisioned by the manufacturer. Upon first device boot, if a pre-provisioned attestation key (ID = PSA_KEY_ID_IAK) is not found, a random key pair will be generated and stored in flash for subsequent usage. The public part of the key pair can be exported by the application for verification of the token signature.
PSA_KEY_ID_IAK is defined in <SDK Root>/source/third_party/tfm/interface/include/psa/crypto_values.h as follows:
#define PSA_KEY_ID_IAK ((psa_key_id_t) 0x7fff815d)
Attestation Requirements¶
To ensure the contents of the attestation token can be trusted:
Secure Boot must be enabled to authenticate the integrity of the TF-M image when using attestation since the token claims for boot seed and security lifecycle require it.
Debug authentication in the CCFG must be setup to either FORBID, NON-INVASIVE ONLY, or REQUIRE AUTHORIZATION to ensure the correct security lifecycle can be reported. When REQUIRE AUTHORIZATION is selected, only authorized trusted users can enter the PSA RoT Debug lifecycle state which allows secure memory to be read and potentially written.
Supported APIs¶
PSA Certified Attestation API 1.0 are supported.
1/**
2 * \brief Get initial attestation token
3 *
4 * \param[in] auth_challenge Pointer to buffer where challenge input is
5 * stored. Nonce and / or hash of attested data.
6 * Must be always
7 * \ref PSA_INITIAL_ATTEST_TOKEN_SIZE bytes
8 * long.
9 * \param[in] challenge_size Size of challenge object in bytes.
10 * \param[out] token_buf Pointer to the buffer where attestation token
11 * will be stored.
12 * \param[in] token_buf_size Size of allocated buffer for token, in bytes.
13 * \param[out] token_size Size of the token that has been returned, in
14 * bytes.
15 *
16 * \return Returns error code as specified in \ref psa_status_t
17 */
18psa_status_t
19psa_initial_attest_get_token(const uint8_t *auth_challenge,
20 size_t challenge_size,
21 uint8_t *token_buf,
22 size_t token_buf_size,
23 size_t *token_size);
24
25/**
26 * \brief Get the exact size of initial attestation token in bytes.
27 *
28 * It just returns with the size of the IAT token. It can be used if the caller
29 * dynamically allocates memory for the token buffer.
30 *
31 * \param[in] challenge_size Size of challenge object in bytes. This must be
32 * a supported challenge size (as above).
33 * \param[out] token_size Size of the token in bytes, which is created by
34 * initial attestation service.
35 *
36 * \return Returns error code as specified in \ref psa_status_t
37 */
38psa_status_t
39psa_initial_attest_get_token_size(size_t challenge_size,
40 size_t *token_size);
Configurability¶
These configurability options are available in <SDK Root>/tfm_s/cc27xx/production_full/config/config_tfm_project.h:
1/* Include optional verification service claim and certification reference
2 * claims in initial attestation token.
3 *
4 * If optional claims are enabled, the certification reference value in
5 * <SDK>/source/third_party/tfm/platform/ext/target/ti/cc27xx/attest_hal.c must
6 * be updated with the certification number provided by the certification
7 * authority.
8 */
9#define ATTEST_INCLUDE_OPTIONAL_CLAIMS 0