interface/include/psa_initial_attestation_api.h

/*
 * 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__ */