| /* |
| * Copyright (c) 2018-2019, Arm Limited. All rights reserved. |
| * |
| * SPDX-License-Identifier: BSD-3-Clause |
| * |
| */ |
| |
| /***************************************************************************/ |
| /* DRAFT UNDER REVIEW */ |
| /* These APIs are still evolving and are meant as a prototype for review.*/ |
| /* The APIs will change depending on feedback and will be firmed up */ |
| /* to a stable set of APIs once all the feedback has been considered. */ |
| /***************************************************************************/ |
| |
| #ifndef __PSA_INITIAL_ATTESTATION_API_H__ |
| #define __PSA_INITIAL_ATTESTATION_API_H__ |
| |
| #include "tfm_api.h" |
| #include <limits.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * \brief PSA INITIAL ATTESTATION API version |
| */ |
| #define PSA_INITIAL_ATTEST_API_VERSION_MAJOR (0) |
| #define PSA_INITIAL_ATTEST_API_VERSION_MINOR (1) |
| |
| /* The return value is shared with the TFM partition status value. The ATTEST |
| * return codes shouldn't overlap with predefined TFM status values. |
| */ |
| #define PSA_ATTEST_ERR_OFFSET (TFM_PARTITION_SPECIFIC_ERROR_MIN) |
| |
| /** |
| * \enum psa_attest_err_t |
| * |
| * \brief Initial attestation service error types |
| * |
| */ |
| enum psa_attest_err_t { |
| /** Action was performed successfully */ |
| PSA_ATTEST_ERR_SUCCESS = 0, |
| /** Boot status data is unavailable or malformed */ |
| PSA_ATTEST_ERR_INIT_FAILED = PSA_ATTEST_ERR_OFFSET, |
| /** Token buffer is too small to store the created token there */ |
| PSA_ATTEST_ERR_TOKEN_BUFFER_OVERFLOW, |
| /** Some of the mandatory claims are unavailable*/ |
| PSA_ATTEST_ERR_CLAIM_UNAVAILABLE, |
| /** 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_INVALID_INPUT, |
| /** Unexpected error happened during operation */ |
| PSA_ATTEST_ERR_GENERAL, |
| /** Following entry is only to ensure the error code of integer size */ |
| PSA_ATTEST_ERR_FORCE_INT_SIZE = INT_MAX |
| }; |
| |
| /** |
| * 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. |
| */ |
| #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32 (32u) |
| #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48 (48u) |
| #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64 (64u) |
| |
| #define PSA_INITIAL_ATTEST_MAX_CHALLENGE_SIZE (64u) |
| |
| /** |
| * 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. |
| */ |
| |
| /** |
| * Calculated based on: |
| * - COSE header |
| * - Algorithm identifier |
| * - Key ID |
| * - Claims in initial attestation token |
| * - COSE Signature |
| * |
| * This size (in bytes) is a maximum value, actual token size can be smaller. |
| */ |
| /* FixMe: Just initial value it must be updated if claims are fixed */ |
| #define PSA_INITIAL_ATTEST_TOKEN_SIZE (512u) |
| |
| /** |
| * \brief Get initial attestation token |
| * |
| * \param[in] challenge_obj Pointer to buffer where challenge input is |
| * stored. Nonce and / or hash of attested data. |
| * Must be always |
| * \ref PSA_INITIAL_ATTEST_CHALLENGE_SIZE bytes |
| * long. |
| * \param[in] challenge_size Size of challenge object in bytes. |
| * \param[out] token Pointer to the buffer where attestation token |
| * must be stored. |
| * \param[in/out] token_size Size of allocated buffer for token, which |
| * updated by initial attestation service with |
| * final token size. |
| * |
| * \return Returns error code as specified in \ref psa_attest_err_t |
| */ |
| 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); |
| |
| /** |
| * \brief 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. |
| * |
| * \param[in] challenge_size Size of challenge object in bytes. |
| * \param[out] token_size Size of the token in bytes, which is created by |
| * initial attestation service. |
| * |
| * \return Returns error code as specified in \ref psa_attest_err_t |
| */ |
| enum psa_attest_err_t |
| psa_initial_attest_get_token_size(uint32_t challenge_size, |
| uint32_t *token_size); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* __PSA_INITIAL_ATTESTATION_API_H__ */ |