SE RT Services Utilities library

| SE RT Services Utilities library

Functions
Initial Attestation Token
IFX SE Generic Syscall API

## 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