1 /*
2 * Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7 #ifndef CLAIM_H
8 #define CLAIM_H
9
10 #include <stddef.h>
11 #include <stdbool.h>
12 #include <stdint.h>
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 struct claim;
19
20 /**
21 * An iterator for accessing claims within a collection. A concrete
22 * claim_iterator provides functions that understand a specific
23 * representation of measurements or observations.
24 */
25 struct claim_iterator
26 {
27 /**
28 * Initialise the iterator to the first claim
29 * in a collection.
30 */
31 void (*first)(struct claim_iterator *iter);
32
33 /**
34 * Advance the iterator to the next claim
35 * in a collection. Returns true if successful.
36 */
37 bool (*next)(struct claim_iterator *iter);
38
39 /**
40 * Check if iterator has reached the end of
41 * the collection.
42 */
43 bool (*is_done)(struct claim_iterator *iter);
44
45 /**
46 * Access the claim at the current iterator position.
47 * Returns true if there is a valid claim, else false.
48 */
49 bool (*current)(struct claim_iterator *iter, struct claim *claim);
50
51 /* Abstract handle marking the beginning of a collection */
52 const void *begin_pos;
53
54 /* Abstract handle marking the end of a collection */
55 const void *end_pos;
56
57 /* Abstract handle marking the current iterator position */
58 const void *cur_pos;
59 };
60
61 /**
62 * Claim variants for different types of claim.
63 */
64
65 /* A variant for integer value claims */
66 struct integer_claim_variant
67 {
68 int32_t value;
69 };
70
71 /* A variant for zero terminated text string claims */
72 struct text_string_claim_variant
73 {
74 const char *string;
75 };
76
77 /* A variant for byte array claims */
78 struct byte_string_claim_variant
79 {
80 size_t len;
81 const uint8_t *bytes;
82 };
83
84 /* A variant for measurement claims that carry a digest that
85 * refects the security state of the mesaured component.
86 */
87 struct measurement_claim_variant
88 {
89 struct text_string_claim_variant id;
90 struct byte_string_claim_variant digest;
91 };
92
93 /* A variant that is a container for 0..* claim objects */
94 struct claim_collection_variant
95 {
96 void (*create_iterator)(const struct claim_collection_variant *variant,
97 struct claim_iterator *iter);
98
99 const void *begin_pos;
100 const void *end_pos;
101 };
102
103 /**
104 * \brief Initializes an iterator to access a concrete claim collection
105 *
106 * \param[in] variant The claim variant to access
107 * \param[out] iter The iterator to initialize
108 */
claim_collection_variant_create_iterator(const struct claim_collection_variant * variant,struct claim_iterator * iter)109 static inline void claim_collection_variant_create_iterator(
110 const struct claim_collection_variant *variant,
111 struct claim_iterator *iter)
112 {
113 variant->create_iterator(variant, iter);
114 }
115
116 /**
117 * Claim category. Values may be combined in a bitmap
118 * to allow a set of categries to be expressed.
119 */
120 enum claim_category
121 {
122 CLAIM_CATEGORY_NONE = 0,
123
124 /**
125 * A catagory of claim about the device instance.
126 */
127 CLAIM_CATEGORY_DEVICE = (1U << 0),
128
129 /**
130 * A catagory of claim based on a measurement during boot.
131 */
132 CLAIM_CATEGORY_BOOT_MEASUREMENT = (1U << 1),
133
134 /**
135 * A catagory of claim about an associated verifcation service.
136 */
137 CLAIM_CATEGORY_VERIFICATION_SERVICE = (1U << 2)
138 };
139
140 /**
141 * Claim subject identifier. Used for identifying what the claim relates
142 * to.
143 */
144 enum claim_subject_id
145 {
146 CLAIM_SUBJECT_ID_NONE = 0,
147 CLAIM_SUBJECT_ID_AUTH_CHALLENGE,
148 CLAIM_SUBJECT_ID_INSTANCE_ID,
149 CLAIM_SUBJECT_ID_VERIFICATION_SERVICE_INDICATOR,
150 CLAIM_SUBJECT_ID_PROFILE_DEFINITION,
151 CLAIM_SUBJECT_ID_IMPLEMENTATION_ID,
152 CLAIM_SUBJECT_ID_CLIENT_ID,
153 CLAIM_SUBJECT_ID_LIFECYCLE_STATE,
154 CLAIM_SUBJECT_ID_HW_VERSION,
155 CLAIM_SUBJECT_ID_BOOT_SEED,
156 CLAIM_SUBJECT_ID_NO_SW_MEASUREMENTS,
157 CLAIM_SUBJECT_ID_SW_COMPONENT
158 };
159
160 /**
161 * Claim variant identifier. Identifies the concrete claim variant.
162 */
163 enum claim_variant_id
164 {
165 CLAIM_VARIANT_ID_UNSUPPORTED,
166 CLAIM_VARIANT_ID_INTEGER,
167 CLAIM_VARIANT_ID_TEXT_STRING,
168 CLAIM_VARIANT_ID_BYTE_STRING,
169 CLAIM_VARIANT_ID_MEASUREMENT,
170 CLAIM_VARIANT_ID_COLLECTION
171 };
172
173 /**
174 * The common claim structure, holds a particular variant, identified
175 * by the variant_id. A claim may be an arbitrarily deep tree or just
176 * a single node.
177 */
178 struct claim
179 {
180 enum claim_category category;
181 enum claim_subject_id subject_id;
182 enum claim_variant_id variant_id;
183
184 /* Pointer to the raw record. Allows a client with
185 * knowledge of the record format to access additional
186 * information. NULL if not available.
187 */
188 const uint8_t *raw_data;
189
190 union claim_variant
191 {
192 struct integer_claim_variant integer;
193 struct text_string_claim_variant text_string;
194 struct byte_string_claim_variant byte_string;
195 struct measurement_claim_variant measurement;
196 struct claim_collection_variant collection;
197
198 } variant;
199 };
200
201 #ifdef __cplusplus
202 } /* extern "C" */
203 #endif
204
205 #endif /* CLAIM_H */
206