General Description

Initial Attestation Token definitions.

SE RT Services supports Initial Attestation Token generation according to "Arm's Platform Security Architecture (PSA) Attestation Token" RFC document https://datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token/.

SE RT Services provide Initial Attestation token generation in next steps:

set shared data (measurements) of images by L1 and L2 bootloaders using ifx_se_set_shared_data API.
get Initial Attestation token size to allocate memory buffer for token
get Initial Attestation token into provided buffer

Shared data can be locked to prevent any changes of measurements using ifx_se_lock_shared_data API.

Storage for shared data supports up to 7 data blocks of 0x80 bytes, for IDs from 0 to 6.

Attestation token ifx_se_initial_attest_get_token_size API returns MAXIMAL size of possible generated token in CBOR format calculated from:

maximal size of challenge, 64 bytes
size of Client ID, 4 bytes (integer value)
maximal size of Verification Services, 32 bytes
maximal size of Certification Reference (Hardware version), 19 bytes (EAN-13-5 string)
maximal size of Profile definition, 32 bytes
maximal size of Implementation ID, 32 bytes
maximal size of Instance ID, 33 bytes
maximal size of Security lifecycle, 4 bytes (integer value)
maximal size of Boot seed, 32 bytes
software components data claim
set of uploaded shared data blocks, max 0x80 per block
system assets information for ROMBoot, RRAMBoot, L1_Boot, SE RT Services; data block of 384 bytes

Maximal supported token size is 1510 bytes.

Note: SE RT Services supports only PSA 2.0.0 profile.

Software components claim ALWAYS contain information of system assets:

Asset	Name	Version	Descr	Signer_ID	Value
ROMBoot	"ROM boot"	actual asset version		-	-
RRAMBoot	"RRAM boot"	actual asset version	SHA256	-	asset image hash
L1_Boot	"L1 boot"	actual asset version	SHA256	-	asset image hash
SE RT Services	"SE RT Services"	actual asset version	SHA256	hash of the signing key IFX_SE_KEY_ID_BUILTIN_ATTEST	asset image hash

Functions
ifx_se_status_t	ifx_se_set_shared_data (ifx_se_fih_t image_id, const ifx_se_fih_ptr_t data, ifx_se_fih_t data_size, void *ctx)
	Receives the boot status information (also known as measured boot) in TLV format defined by MCUboot and TF-M design pages. More...

ifx_se_status_t	ifx_se_lock_shared_data (void *ctx)
	Locks receiving the boot status information (also known as measured boot) so the shared data can't be modified. More...

ifx_se_status_t	ifx_se_initial_attest_get_token (const ifx_se_fih_ptr_t challenge, ifx_se_fih_t challenge_size, ifx_se_fih_t client_id, const ifx_se_fih_ptr_t verify_svc, ifx_se_fih_t verify_svc_size, const ifx_se_fih_ptr_t hardware_ver, ifx_se_fih_t hardware_ver_size, ifx_se_fih_ptr_t token_data, ifx_se_fih_t token_size, ifx_se_fih_ptr_t token_length, void *ctx)
	Gets Initial Attestation Token created as described in the Initial Attestation Service design page. More...

ifx_se_status_t	ifx_se_initial_attest_get_token_size (ifx_se_fih_t challenge_size, ifx_se_fih_ptr_t token_size, void *ctx)
	Gets Initial Attestation Token maximal size to allocate token buffer. More...

Function Documentation

◆ ifx_se_set_shared_data()

ifx_se_status_t ifx_se_set_shared_data	(	ifx_se_fih_t	image_id,
		const ifx_se_fih_ptr_t	data,
		ifx_se_fih_t	data_size,
		void *	ctx
	)

Receives the boot status information (also known as measured boot) in TLV format defined by MCUboot and TF-M design pages.

Once data integrity is verified it should be stored in RRAM in SE to support DEEP_SLEEP_RAM mode. Only one successful request should be supported per boot process for L1 and L2 Bootloaders, so data can't be modified by the following after OEM L2 Bootloader image. This shared data will be used to create Initial Attestation Token by ifx_se_initial_attest_get_token function.

Parameters

[in]	image_id	The image_id to set shared data (0 to IFX_SE_SHARED_DATA_IMAGES_NUM - 1).
[in]	data	The pointer to the memory buffer.
[in]	data_size	Size of memory buffer (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Returns: IFX_SE_SUCCESS for success or error code

◆ ifx_se_lock_shared_data()

ifx_se_status_t ifx_se_lock_shared_data ( void * ctx )

Locks receiving the boot status information (also known as measured boot) so the shared data can't be modified.

Parameters

[in] ctx The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Returns: IFX_SE_SUCCESS for success or error code

◆ ifx_se_initial_attest_get_token()

ifx_se_status_t ifx_se_initial_attest_get_token	(	const ifx_se_fih_ptr_t	challenge,
		ifx_se_fih_t	challenge_size,
		ifx_se_fih_t	client_id,
		const ifx_se_fih_ptr_t	verify_svc,
		ifx_se_fih_t	verify_svc_size,
		const ifx_se_fih_ptr_t	hardware_ver,
		ifx_se_fih_t	hardware_ver_size,
		ifx_se_fih_ptr_t	token_data,
		ifx_se_fih_t	token_size,
		ifx_se_fih_ptr_t	token_length,
		void *	ctx
	)

Gets Initial Attestation Token created as described in the Initial Attestation Service design page.

It should support only asymmetric key algorithm based attestation (symmetric attestation not supported). It supports all required EAT claims that are defined in the PSA attestation token specification for the new profile (http://arm.com/psa/2.0.0).

Parameters

[in]	challenge	The challenge object.
[in]	challenge_size	The length of the challenge object (size_t).
[in]	client_id	The partition ID of that secure partition or non-secure thread who called the initial attestation API.
[in]	verify_svc	The pointer to verification service id as text string that can be used to locate the service or a URL specifying the address of the service.
[in]	verify_svc_size	The length of the verification service id (size_t).
[in]	hardware_ver	The pointer to the Certification Reference (Hardware version) string that is used to link the class of chip and PSA RoT of the attesting device to an associated entry in the PSA Certification database. Must be represented as EAN-13-5 formatted string.
[in]	hardware_ver_size	The length of the hardware version (size_t).
[out]	token_data	The pointer to the token buffer.
[in]	token_size	The size of the token buffer (size_t).
[out]	token_length	The pointer to the actual size of the generated attestation token (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Returns: IFX_SE_SUCCESS for success or error code

Note

For Secure device LCS the LIFECYCLE claim will contain "Recoverable PSA RoT Debug" value with additional debug state in the lowest byte instead of "Secured" when opened or allowed at least one debug AP:

*                          bits [2:0] - CM33 policy debug AP configuration:
*                            000 - Disabled, CPU debugging is not allowed, and
*                                  will be permanently disabled during boot.
*                            001 - Enabled, CPU debugging will be enabled
*                                  during boot.
*                            010 - Allowed + Firmware, trusted Firmware can
*                                  directly access DAP control register.
*                            011 - Allowed + Certificate, firmware or SYS-AP
*                                  must provide a debug certificate.
*                            100 - Allowed + Open, any firmware can
*                                  directly access DAP control register.
*                          bit [3] - CM0+ debug AP is enabled
*                          bit [4] - device provisioned for non-production
*                                  (development) flow
*

The Implementation ID claim contains device specific data constructed from DIE_ID, DEVICE_ID_TO and DEVICE_ID_MPN fields:

*                          bytes [9:0]   - DIE_ID
*                          bytes [12:10] - DEVICE_ID_TO
*                          bytes [14:13] - DEVICE_ID_MPN
*

◆ ifx_se_initial_attest_get_token_size()

ifx_se_status_t ifx_se_initial_attest_get_token_size	(	ifx_se_fih_t	challenge_size,
		ifx_se_fih_ptr_t	token_size,
		void *	ctx
	)

Gets Initial Attestation Token maximal size to allocate token buffer.

Use this value to allocate space for ifx_se_initial_attest_get_token.

Parameters

[in]	challenge_size	The length of the challenge object (size_t).
[out]	token_size	The pointer to the actual length of the attestation token (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Returns: IFX_SE_SUCCESS for success or error code

General Description

Functions

Function Documentation

◆ ifx_se_set_shared_data()

◆ ifx_se_lock_shared_data()

◆ ifx_se_initial_attest_get_token()

◆ ifx_se_initial_attest_get_token_size()