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