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