mirror of https://github.com/ARMmbed/mbed-os.git
227 lines
10 KiB
C
227 lines
10 KiB
C
/*
|
|
* 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 <limits.h>
|
|
#include <stdint.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 (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)
|
|
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48 (48u)
|
|
#define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64 (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.
|
|
*/
|
|
|
|
/**
|
|
* \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__ */
|