psa_initial_attestation_api.h

Go to the documentation of this file.

/*
 * 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.    */
/***************************************************************************/
 
/** @defgroup PSA-Attestation PSA-Attestation
    @ingroup experimental-crypto-psa
 * @{
 */
 
 
#ifndef __PSA_INITIAL_ATTESTATION_API_H__
#define __PSA_INITIAL_ATTESTATION_API_H__
 
#include <limits.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/**
* \file
* 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:
*  <ul>
*  <li> \b 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.</li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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: <ul>
*                   <li> version[15:8] - PSA lifecycle state - major </li>
*                   <li> version[7:0]  - IMPLEMENTATION DEFINED state - minor </li> </ul>
*                 Possible PSA lifecycle states: <ul>
*                  <li> Unknown (0x1000u) </li>
*                  <li> PSA_RoT_Provisioning (0x2000u)</li>
*                  <li> Secured (0x3000u) </li>
*                  <li> Non_PSA_RoT_Debug(0x4000u) </li>
*                  <li> Recoverable_PSA_RoT_Debug (0x5000u) </li>
*                  <li> Decommissioned (0x6000u) </li> </ul> </li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
 
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b Measurement type: Optional claim. It represents the role of the
*                    software component. Value is encoded as short(!) text
*                    string. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b Security epoch: Optional claim. It represents the security control
*                    point of the software component. Value is encoded as
*                    unsigned integer. </li>
*
*  <li> \b Version:     Optional claim. It represents the issued software version.
*                    Value is encoded as text string. </li>
*
*  <li> \b Signer ID:   It represents the hash of a signing authority public key.
*                    Value is encoded as byte string. </li>
*
*  <li> \b 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. </li>
*
*  <li> \b 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. </li>
* </ul>
*/
 
/**
 * \brief PSA INITIAL ATTESTATION API version
 */
#define PSA_INITIAL_ATTEST_API_VERSION_MAJOR (0)
#define PSA_INITIAL_ATTEST_API_VERSION_MINOR (9)
 
/**
 * \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,
    /** 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)  ///< 32 byte challenge
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48  (48u)  ///< 48 byte challenge
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64  (64u)  ///< 64 byte challenge
 
/**
 * \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 have a length equal to one of the
 *                                PSA_INITIAL_ATTEST_CHALLENGE_SIZE_xxx constants.
 * \param[in]     challenge_size  Size of challenge object in bytes.
 * \param[out]    token           Pointer to the buffer where attestation token
 *                                must be stored.
 * \param[inout] 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
 
/** @}*/ // PSA-Attestation
 
#endif /* __PSA_INITIAL_ATTESTATION_API_H__ */