Mbed OS Reference
Loading...
Searching...
No Matches
psa_initial_attestation_api.h File Reference

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

#include <limits.h>
#include <stdint.h>

Go to the source code of this file.

Macros

#define PSA_INITIAL_ATTEST_API_VERSION_MAJOR   (0)
 PSA INITIAL ATTESTATION API version. More...
 
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32   (32u)
 32 byte challenge More...
 
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48   (48u)
 48 byte challenge More...
 
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64   (64u)
 64 byte challenge More...
 

Enumerations

enum  psa_attest_err_t {
  PSA_ATTEST_ERR_SUCCESS = 0 , PSA_ATTEST_ERR_INIT_FAILED , PSA_ATTEST_ERR_TOKEN_BUFFER_OVERFLOW , PSA_ATTEST_ERR_CLAIM_UNAVAILABLE ,
  PSA_ATTEST_ERR_INVALID_INPUT , PSA_ATTEST_ERR_GENERAL , PSA_ATTEST_ERR_FORCE_INT_SIZE = INT_MAX
}
 Initial attestation service error types. More...
 

Functions

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)
 Get initial attestation token. 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

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.

Definition in file psa_initial_attestation_api.h.