Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM_LATEST/include/psa/initial_attestation.h
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 /***************************************************************************/
9 /* DRAFT UNDER REVIEW */
10 /* These APIs are still evolving and are meant as a prototype for review.*/
11 /* The APIs will change depending on feedback and will be firmed up */
12 /* to a stable set of APIs once all the feedback has been considered. */
13 /***************************************************************************/
14 
15 #ifndef __PSA_INITIAL_ATTESTATION_H__
16 #define __PSA_INITIAL_ATTESTATION_H__
17 
18 #include <limits.h>
19 #include <stdint.h>
20 #include <stddef.h>
21 #include "psa/crypto.h"
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 /**
28  * \brief PSA INITIAL ATTESTATION API version
29  *
30  * Initial attestation API version is: 1.0.0
31  */
32 #define PSA_INITIAL_ATTEST_API_VERSION_MAJOR (1)
33 #define PSA_INITIAL_ATTEST_API_VERSION_MINOR (0)
34 
35 /**
36  * The allowed size of input challenge in bytes: 32, 48, 64
37  * Challenge can be a nonce from server
38  * or the hash of some combined data : nonce + attested data by caller.
39  */
40 #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_32 (32u)
41 #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_48 (48u)
42 #define PSA_INITIAL_ATTEST_CHALLENGE_SIZE_64 (64u)
43 
44 /**
45  * The maximum size of an attestation token that can be generated by the
46  * attestation service. Used to configure buffers for services that verify the
47  * produced tokens.
48  */
49 #define PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE (0x400)
50 
51 /**
52  * The list of fixed claims in the initial attestation token is still evolving,
53  * you can expect slight changes in the future.
54  *
55  * The initial attestation token is planned to be aligned with future version of
56  * Entity Attestation Token format:
57  * https://tools.ietf.org/html/draft-mandyam-eat-01
58  *
59  * Current list of claims:
60  * - Challenge: Input object from caller. Can be a single nonce from server
61  * or hash of nonce and attested data. It is intended to provide
62  * freshness to reports and the caller has responsibility to
63  * arrange this. Allowed length: 32, 48, 64 bytes. The claim is
64  * modeled to be eventually represented by the EAT standard
65  * claim nonce. Until such a time as that standard exists,
66  * the claim will be represented by a custom claim. Value
67  * is encoded as byte string.
68  *
69  * - Instance ID: It represents the unique identifier of the instance. In the
70  * PSA definition it is a hash of the public attestation key
71  * of the instance. The claim is modeled to be eventually
72  * represented by the EAT standard claim UEID of type GUID.
73  * Until such a time as that standard exists, the claim will be
74  * represented by a custom claim Value is encoded as byte
75  * string.
76  *
77  * - Verification service indicator: Optional, recommended claim. It is used by
78  * a Relying Party to locate a validation service for the token.
79  * The value is a text string that can be used to locate the
80  * service or a URL specifying the address of the service. The
81  * claim is modeled to be eventually represented by the EAT
82  * standard claim origination. Until such a time as that
83  * standard exists, the claim will be represented by a custom
84  * claim. Value is encoded as text string.
85  *
86  * - Profile definition: Optional, recommended claim. It contains the name of
87  * a document that describes the 'profile' of the token, being
88  * a full description of the claims, their usage, verification
89  * and token signing. The document name may include versioning.
90  * Custom claim with a value encoded as text string.
91  *
92  * - Implementation ID: It represents the original implementation signer of the
93  * attestation key and identifies the contract between the
94  * report and verification. A verification service will use this
95  * claim to locate the details of the verification process.
96  * Custom claim with a value encoded as byte string.
97  *
98  * - Security lifecycle: It represents the current lifecycle state of the
99  * instance. Custom claim with a value encoded as integer that
100  * is divided to convey a major state and a minor state. The
101  * PSA state and implementation state are encoded as follows:
102  * - version[15:8] - PSA lifecycle state - major
103  * - version[7:0] - IMPLEMENTATION DEFINED state - minor
104  * Possible PSA lifecycle states:
105  * - Unknown (0x1000u),
106  * - PSA_RoT_Provisioning (0x2000u),
107  * - Secured (0x3000u),
108  * - Non_PSA_RoT_Debug(0x4000u),
109  * - Recoverable_PSA_RoT_Debug (0x5000u),
110  * - Decommissioned (0x6000u)
111  *
112  * - Client ID: The partition ID of that secure partition or non-secure
113  * thread who called the initial attestation API. Custom claim
114  * with a value encoded as a *signed* integer. Negative number
115  * represents non-secure caller, positive numbers represents
116  * secure callers, zero is invalid.
117  *
118  * - HW version: Optional claim. Globally unique number in EAN-13 format
119  * identifying the GDSII that went to fabrication, HW and ROM.
120  * It can be used to reference the security level of the PSA-ROT
121  * via a certification website. Custom claim with a value is
122  * encoded as text string.
123 
124  * - Boot seed: It represents a random value created at system boot time that
125  * will allow differentiation of reports from different system
126  * sessions. The size is 32 bytes. Custom claim with a value is
127  * encoded as byte string.
128  *
129  * - Software components: Recommended claim. It represents the software state
130  * of the system. The value of the claim is an array of CBOR map
131  * entries, with one entry per software component within the
132  * device. Each map contains multiple claims that describe
133  * evidence about the details of the software component.
134  *
135  * - Measurement type: Optional claim. It represents the role of the
136  * software component. Value is encoded as short(!) text
137  * string.
138  *
139  * - Measurement value: It represents a hash of the invariant software
140  * component in memory at start-up time. The value must be a
141  * cryptographic hash of 256 bits or stronger.Value is
142  * encoded as byte string.
143  *
144  * - Version: Optional claim. It represents the issued software version.
145  * Value is encoded as text string.
146  *
147  * - Signer ID: It represents the hash of a signing authority public key.
148  * Value is encoded as byte string.
149  *
150  * - Measurement description: Optional claim. It represents the way in which
151  * the measurement value of the software component is
152  * computed. Value is encoded as text string containing an
153  * abbreviated description (name) of the measurement method.
154  *
155  * - No software measurements: In the event that the implementation does not
156  * contain any software measurements then the software
157  * components claim above can be omitted but instead
158  * it is mandatory to include this claim to indicate this is a
159  * deliberate state. Custom claim a value is encoded as unsigned
160  * integer set to 1.
161  */
162 
163 /**
164  * \brief Get initial attestation token
165  *
166  * \param[in] auth_challenge Pointer to buffer where challenge input is
167  * stored. Nonce and / or hash of attested data.
168  * Must be always
169  * \ref PSA_INITIAL_ATTEST_TOKEN_SIZE bytes
170  * long.
171  * \param[in] challenge_size Size of challenge object in bytes.
172  * \param[out] token_buf Pointer to the buffer where attestation token
173  * will be stored.
174  * \param[in] token_buf_size Size of allocated buffer for token, in bytes.
175  * \param[out] token_size Size of the token that has been returned, in
176  * bytes.
177  *
178  * \return Returns error code as specified in \ref psa_status_t
179  */
180 psa_status_t
181 psa_initial_attest_get_token(const uint8_t *auth_challenge,
182  size_t challenge_size,
183  uint8_t *token_buf,
184  size_t token_buf_size,
185  size_t *token_size);
186 
187 /**
188  * \brief Get the exact size of initial attestation token in bytes.
189  *
190  * It just returns with the size of the IAT token. It can be used if the caller
191  * dynamically allocates memory for the token buffer.
192  *
193  * \param[in] challenge_size Size of challenge object in bytes. This must be
194  * a supported challenge size (as above).
195  * \param[out] token_size Size of the token in bytes, which is created by
196  * initial attestation service.
197  *
198  * \return Returns error code as specified in \ref psa_status_t
199  */
200 psa_status_t
201 psa_initial_attest_get_token_size(size_t challenge_size,
202  size_t *token_size);
203 
204 /**
205  * \brief Get the initial attestation public key.
206  *
207  * \param[out] public_key Pointer to the buffer where the public key
208  * will be stored.
209  * \param[in] key_buf_size Size of allocated buffer for key, in bytes.
210  * \param[out] public_key_len Size of public key in bytes.
211  * \param[out] public_key_curve Type of the elliptic curve which the key
212  * belongs to.
213  *
214  * \note Currently only the ECDSA P-256 over SHA-256 algorithm is supported.
215  *
216  * \return Returns error code as specified in \ref psa_status_t
217  */
218 psa_status_t
219 tfm_initial_attest_get_public_key(uint8_t *public_key,
220  size_t public_key_buf_size,
221  size_t *public_key_len,
222  psa_ecc_family_t *elliptic_curve_type);
223 
224 #ifdef __cplusplus
225 }
226 #endif
227 
228 #endif /* __PSA_INITIAL_ATTESTATION_H__ */
psa_initial_attest_get_token_size
enum psa_attest_err_t psa_initial_attest_get_token_size(uint32_t challenge_size, uint32_t *token_size)
Get the exact size of initial attestation token in bytes.
psa_initial_attest_get_token
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)
The list of fixed claims in the initial attestation token is still evolving, you can expect slight ch...
psa_ecc_family_t
uint8_t psa_ecc_family_t
The type of PSA elliptic curve family identifiers.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:75
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:53
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.