Attest: Update initial attestation header
- extend API to get the size of the token
- update the list of claims and add more elaborate
description
Change-Id: Id0f0a1735c83ef780c31634fcfeb07d6a7b41184
Signed-off-by: Tamas Ban <tamas.ban@arm.com>
diff --git a/interface/include/psa_initial_attestation_api.h b/interface/include/psa_initial_attestation_api.h
index 1656615..9c0c162 100644
--- a/interface/include/psa_initial_attestation_api.h
+++ b/interface/include/psa_initial_attestation_api.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -40,41 +40,151 @@
*
*/
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 int size */
+ /** Following entry is only to ensure the error code of integer size */
PSA_ATTEST_ERR_FORCE_INT_SIZE = INT_MAX
};
/**
- * Maximum size of input challenge in bytes. This can be a nonce from server or
- * the hash of any data which must be attested to the server.
+ * 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 later version of
+ * 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-00
+ * https://tools.ietf.org/html/draft-mandyam-eat-01
*
* Current list of claims:
- * - Challenge: Input object from caller. Can be nonce from server or hash of
- * attested data.
- * - Client ID: The ID of that secure partition or non-secure thread who
- * called the initial attestation API.
- * - Boot status: Measurements(hash) of firmware components by secure
- * bootloader.
- * - Boot seed: Random number, which is constant during the same boot cycle.
- * - Device ID: Universally and globally unique ID of the device.
- * - HW version: Uniquely identifies the GDSII that went to fabrication, HW
- * and ROM.
+ * - 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.
*/
/**
@@ -82,7 +192,7 @@
* - COSE header
* - Algorithm identifier
* - Key ID
- * - Claims in initial attestation token:
+ * - Claims in initial attestation token
* - COSE Signature
*
* This size (in bytes) is a maximum value, actual token size can be smaller.
@@ -113,6 +223,22 @@
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