Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
Macros | Enumerations | Functions
PSA-Attestation

Macros

#define PSA_INITIAL_ATTEST_API_VERSION_MAJOR   (0)
 PSA INITIAL ATTESTATION API version. More...
 
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32   (32u)
 The allowed size of input challenge in bytes: 32, 48, 64 Challenge can be a nonce from server or the hash of some combined data : nonce + attested data by caller. More...
 

Enumerations

Functions

enum psa_attest_err_t attest_get_boot_data (uint8_t major_type, void *ptr, uint32_t len)
 Copy the boot data (coming from boot loader) from shared memory area to service memory area. More...
 
enum psa_attest_err_t attest_get_caller_client_id (int32_t *caller_id)
 Get the ID of the caller thread. More...
 
enum psa_attest_err_t attest_check_memory_access (void *addr, uint32_t size, enum attest_memory_access_t access)
 Verify memory access rights. More...
 
enum psa_attest_err_t attest_init (void)
 Initialise the initial attestation service during the TF-M boot up process. More...
 
enum psa_attest_err_t initial_attest_get_token (const psa_invec *in_vec, uint32_t num_invec, psa_outvec *out_vec, uint32_t num_outvec)
 Get initial attestation token. More...
 
enum psa_attest_err_t initial_attest_get_token_size (const psa_invec *in_vec, uint32_t num_invec, psa_outvec *out_vec, uint32_t num_outvec)
 Get the size of the initial attestation token. More...
 
psa_status_t psa_attestation_inject_key (const uint8_t *key_data, size_t key_data_length, psa_key_type_t type, uint8_t *public_key_data, size_t public_key_data_size, size_t *public_key_data_length)
 Generate or import a given key pair and export the public part in a binary format. More...
 
enum psa_attest_err_t psa_initial_attest_get_token (const uint8_t *challenge_obj, uint32_t challenge_size, uint8_t *token, uint32_t *token_size)
 The list of fixed claims in the initial attestation token is still evolving, you can expect slight changes in the future. More...
 
enum psa_attest_err_t psa_initial_attest_get_token_size (uint32_t challenge_size, uint32_t *token_size)
 Get the exact size of initial attestation token in bytes. More...
 

Detailed Description

Macro Definition Documentation

#define PSA_INITIAL_ATTEST_API_VERSION_MAJOR   (0)

PSA INITIAL ATTESTATION API version.

Definition at line 33 of file psa_initial_attestation_api.h.

#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32   (32u)

The allowed size of input challenge in bytes: 32, 48, 64 Challenge can be a nonce from server or the hash of some combined data : nonce + attested data by caller.

Definition at line 68 of file psa_initial_attestation_api.h.

Enumeration Type Documentation

enum attest_memory_access_t

Type of memory access.

Definition at line 26 of file attestation.h.

enum psa_attest_err_t

Initial attestation service error types.

Enumerator
PSA_ATTEST_ERR_SUCCESS 

Action was performed successfully.

PSA_ATTEST_ERR_INIT_FAILED 

Boot status data is unavailable or malformed.

PSA_ATTEST_ERR_TOKEN_BUFFER_OVERFLOW 

Token buffer is too small to store the created token there.

PSA_ATTEST_ERR_CLAIM_UNAVAILABLE 

Some of the mandatory claims are unavailable.

PSA_ATTEST_ERR_INVALID_INPUT 

Some parameter or combination of parameters are recognised as invalid:

  • challenge size is not allowed
  • challenge object is unavailable
  • token buffer is unavailable
PSA_ATTEST_ERR_GENERAL 

Unexpected error happened during operation.

PSA_ATTEST_ERR_FORCE_INT_SIZE 

Following entry is only to ensure the error code of integer size.

Definition at line 42 of file psa_initial_attestation_api.h.

Function Documentation

enum psa_attest_err_t attest_check_memory_access ( void *  addr,
uint32_t  size,
enum attest_memory_access_t  access 
)

Verify memory access rights.

Parameters
[in]addrPointer to the base of the address range to check
[in]sizeSize of the address range to check
[in]accessType of memory access as specified in attest_memory_access
Returns
Returns error code as specified in psa_attest_err_t
enum psa_attest_err_t attest_get_boot_data ( uint8_t  major_type,
void *  ptr,
uint32_t  len 
)

Copy the boot data (coming from boot loader) from shared memory area to service memory area.

Parameters
[in]major_typeMajor type of TLV entries to copy
[out]ptrPointer to the buffer to store the boot data [in] len Size of the buffer to store the boot data
Returns
Returns error code as specified in psa_attest_err_t
enum psa_attest_err_t attest_get_caller_client_id ( int32_t *  caller_id)

Get the ID of the caller thread.

Parameters
[out]caller_idPointer where to store caller ID
Returns
Returns error code as specified in psa_attest_err_t
enum psa_attest_err_t attest_init ( void  )

Initialise the initial attestation service during the TF-M boot up process.

Returns
Returns PSA_ATTEST_ERR_SUCCESS if init has been completed, otherwise error as specified in psa_attest_err_t
enum psa_attest_err_t initial_attest_get_token ( const psa_invec *  in_vec,
uint32_t  num_invec,
psa_outvec *  out_vec,
uint32_t  num_outvec 
)

Get initial attestation token.

Parameters
[in]in_vecPointer to in_vec array, which contains input data to attestation service
[in]num_invecNumber of elements in in_vec array
enum psa_attest_err_t initial_attest_get_token_size ( const psa_invec *  in_vec,
uint32_t  num_invec,
psa_outvec *  out_vec,
uint32_t  num_outvec 
)

Get the size of the initial attestation token.

Parameters
[in]in_vecPointer to in_vec array, which contains input data to attestation service
[in]num_invecNumber of elements in in_vec array
[out]out_vecPointer to out_vec array, which contains pointer where to store the output data
[in]num_outvecNumber of elements in out_vec array
Returns
Returns error code as specified in psa_attest_err_t
psa_status_t psa_attestation_inject_key ( const uint8_t *  key_data,
size_t  key_data_length,
psa_key_type_t  type,
uint8_t *  public_key_data,
size_t  public_key_data_size,
size_t *  public_key_data_length 
)

Generate or import a given key pair and export the public part in a binary format.

Initial attestation key: Private key for ECDSA-P256 to sign initial attestation token. Attestation private key is a persistent key that saved to persistent storage with persistent storage id = 17.

Parameters
[in]key_dataBuffer containing the private key data if given. It must conain the format described in the documentation of psa_export_public_key() for the chosen type. In case of generate the private key - NULL will pass.
key_data_lengthSize of the data buffer in bytes - must be 256 bits. in case key_data isn't NULL. In case of private key generation - 0 will pass.
typeKey type - must be a ECC key type (a PSA_KEY_TYPE_ECC_KEYPAIR(PSA_ECC_CURVE_XXX) value).
[out]dataBuffer where the key data is to be written.
data_sizeSize of the data buffer in bytes - needs to be bigger then the max size of the public part.
[out]data_lengthOn success, the number of bytes that make up the key data.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
#PSA_ERROR_OCCUPIED_SLOTThere is already a key in the specified slot.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
#PSA_ERROR_TAMPERING_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
enum psa_attest_err_t psa_initial_attest_get_token ( const uint8_t *  challenge_obj,
uint32_t  challenge_size,
uint8_t *  token,
uint32_t *  token_size 
)

The list of fixed claims in the initial attestation token is still evolving, you can expect slight changes in the future.

The initial attestation token is planned to be aligned with future version of Entity Attestation Token format: https://tools.ietf.org/html/draft-mandyam-eat-01

Current list of claims:

  • Challenge: Input object from caller. Can be a single nonce from server or hash of nonce and attested data. It is intended to provide freshness to reports and the caller has responsibility to arrange this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be eventually represented by the EAT standard claim nonce. Until such a time as that standard exists, the claim will be represented by a custom claim. Value is encoded as byte string.
  • Instance ID: It represents the unique identifier of the instance. In the PSA definition it is a hash of the public attestation key of the instance. The claim is modeled to be eventually represented by the EAT standard claim UEID of type GUID. Until such a time as that standard exists, the claim will be represented by a custom claim Value is encoded as byte string.
  • Verification service indicator: Optional, recommended claim. It is used by a Relying Party to locate a validation service for the token. The value is a text string that can be used to locate the service or a URL specifying the address of the service. The claim is modeled to be eventually represented by the EAT standard claim origination. Until such a time as that standard exists, the claim will be represented by a custom claim. Value is encoded as text string.
  • Profile definition: Optional, recommended claim. It contains the name of a document that describes the 'profile' of the token, being a full description of the claims, their usage, verification and token signing. The document name may include versioning. Custom claim with a value encoded as text string.
  • Implementation ID: It represents the original implementation signer of the attestation key and identifies the contract between the report and verification. A verification service will use this claim to locate the details of the verification process. Custom claim with a value encoded as byte string.
  • Security lifecycle: It represents the current lifecycle state of the instance. Custom claim with a value encoded as integer that is divided to convey a major state and a minor state. The PSA state and implementation state are encoded as follows:
    • version[15:8] - PSA lifecycle state - major
    • version[7:0] - IMPLEMENTATION DEFINED state - minor Possible PSA lifecycle states:

Unknown (0x1000u),

  • PSA_RoT_Provisioning (0x2000u),
  • Secured (0x3000u),
  • Non_PSA_RoT_Debug(0x4000u),
  • Recoverable_PSA_RoT_Debug (0x5000u),
  • Decommissioned (0x6000u)

Client ID: The partition ID of that secure partition or non-secure thread who called the initial attestation API. Custom claim with a value encoded as a signed integer. Negative number represents non-secure caller, positive numbers represents secure callers, zero is invalid.

  • HW version: Optional claim. Globally unique number in EAN-13 format identifying the 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. Custom claim with a value is encoded as text string.
  • Boot seed: It represents a random value created at system boot time that will allow differentiation of reports from different system sessions. The size is 32 bytes. Custom claim with a value is encoded as byte string.
  • Software components: Recommended claim. It represents the software state of the system. The value of the claim is an array of CBOR map entries, with one entry per software component within the device. Each map contains multiple claims that describe evidence about the details of the software component.
    • Measurement type: Optional claim. It represents the role of the software component. Value is encoded as short(!) text string.
    • Measurement value: It represents a hash of the invariant software component in memory at start-up time. The value must be a cryptographic hash of 256 bits or stronger.Value is encoded as byte string.
    • Security epoch: Optional claim. It represents the security control point of the software component. Value is encoded as unsigned integer.
    • Version: Optional claim. It represents the issued software version. Value is encoded as text string.
    • Signer ID: It represents the hash of a signing authority public key. Value is encoded as byte string.
    • Measurement description: Optional claim. It represents the way in which the measurement value of the software component is computed. Value is encoded as text string containing an abbreviated description (name) of the measurement method.
  • No software measurements: 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. Custom claim a value is encoded as unsigned integer set to 1. Get initial attestation token
Parameters
[in]challenge_objPointer to buffer where challenge input is stored. Nonce and / or hash of attested data. Must be always PSA_INITIAL_ATTEST_CHALLENGE_SIZE bytes long.
[in]challenge_sizeSize of challenge object in bytes.
[out]tokenPointer to the buffer where attestation token must be stored.
enum psa_attest_err_t psa_initial_attest_get_token_size ( uint32_t  challenge_size,
uint32_t *  token_size 
)

Get the exact size of initial attestation token in bytes.

It just returns with the size of the IAT token. It can be used if the caller dynamically allocates memory for the token buffer.

Parameters
[in]challenge_sizeSize of challenge object in bytes.
[out]token_sizeSize of the token in bytes, which is created by initial attestation service.
Returns
Returns error code as specified in psa_attest_err_t
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.