1 | /*! |
2 | * @header |
3 | * Image4 environment interfaces. |
4 | */ |
5 | #ifndef __IMG4_ENVIRONMENT_H |
6 | #define __IMG4_ENVIRONMENT_H |
7 | |
8 | #ifndef __IMG4_INDIRECT |
9 | #error "Please #include <img4/img4.h> instead of this file directly" |
10 | #endif // __IMG4_INDIRECT |
11 | |
12 | /*! |
13 | * @const IMG4_ENVIRONMENT_VERSION |
14 | * The version of the {@link img4_environment_t} structure supported by the |
15 | * implementation. See {@link _img4_environment} for complete definition. |
16 | */ |
17 | #define IMG4_ENVIRONMENT_VERSION ((img4_struct_version_t)0) |
18 | |
19 | /*! |
20 | * @typedef img4_crypto_selector_t |
21 | * A CoreCrypto selector routine. |
22 | */ |
23 | IMG4_API_AVAILABLE_20180112 |
24 | typedef const struct ccdigest_info *(*img4_crypto_selector_t)(void); |
25 | |
26 | /*! |
27 | * @typedef img4_crypto_t |
28 | * A structure describing a crypto algorithm used by Image4. |
29 | * |
30 | * @property i4c_name |
31 | * The human-readable string for the crypto algorithm (e.g. "sha1"). |
32 | * |
33 | * @property i4c_select |
34 | * The CoreCrypto selector routine for the algorithm |
35 | * |
36 | * @property i4c_hash_len |
37 | * The length of the hash computed by the algorithm. |
38 | * |
39 | * @property i4c_truncated_hash_len |
40 | * The truncated length of the hash computed by the algorithm. |
41 | * |
42 | * @property __opaque |
43 | * Reserved for the implementation. |
44 | */ |
45 | IMG4_API_AVAILABLE_20180112 |
46 | typedef struct _img4_crypto { |
47 | const char *i4c_name; |
48 | img4_crypto_selector_t i4c_select; |
49 | uint32_t i4c_hash_len; |
50 | uint32_t i4c_truncated_hash_len; |
51 | const void *__opaque; |
52 | } img4_crypto_t; |
53 | |
54 | /*! |
55 | * @const IMG4_CRYPTO_SHA1 |
56 | * The Image4 SHA1 implementation. |
57 | */ |
58 | IMG4_API_AVAILABLE_20180112 |
59 | OS_EXPORT |
60 | const img4_crypto_t _img4_crypto_sha1; |
61 | #define IMG4_CRYPTO_SHA1 (&_img4_crypto_sha1) |
62 | |
63 | /*! |
64 | * @const IMG4_CRYPTO_SHA384 |
65 | * The Image4 SHA-384 implementation. |
66 | */ |
67 | IMG4_API_AVAILABLE_20180112 |
68 | OS_EXPORT |
69 | const img4_crypto_t _img4_crypto_sha384; |
70 | #define IMG4_CRYPTO_SHA384 (&_img4_crypto_sha384) |
71 | |
72 | /*! |
73 | * @typedef img4_environment_t |
74 | * A type describing an Image4 environment. |
75 | */ |
76 | IMG4_API_AVAILABLE_20180112 |
77 | typedef struct _img4_environment img4_environment_t; |
78 | |
79 | /*! |
80 | * @typedef img4_environment_get_crypto_t |
81 | * A function which obtains a crypto descriptor for the host environment. |
82 | * |
83 | * @param i4e |
84 | * The environment descriptor. |
85 | * |
86 | * @param crypto |
87 | * A pointer to the storage in which the pointer to the host's crypto descriptor |
88 | * will be written. |
89 | * |
90 | * @param ctx |
91 | * The context pointer supplied to {@link img4_init}. |
92 | * |
93 | * @result |
94 | * Upon successfully fetching the property value, zero should be returned. |
95 | * Otherwise, the following error codes should be returned: |
96 | * |
97 | * [ENOENT] The property does not exist in the environment |
98 | */ |
99 | IMG4_API_AVAILABLE_20180112 |
100 | typedef errno_t (*img4_environment_get_crypto_t)( |
101 | const img4_environment_t *i4e, |
102 | const img4_crypto_t **crypto, |
103 | const void *ctx); |
104 | |
105 | /*! |
106 | * @typedef img4_environment_get_bool_t |
107 | * A function which obtains a Boolean property from the host environment. |
108 | * |
109 | * @param val |
110 | * A pointer to storage in which the value will be written. |
111 | * |
112 | * @param ctx |
113 | * The context pointer supplied to {@link img4_init}. |
114 | * |
115 | * @result |
116 | * Upon successfully fetching the property value, zero should be returned. |
117 | * Otherwise, the following error codes should be returned: |
118 | * |
119 | * [ENOENT] The property does not exist in the environment |
120 | * [EFTYPE] The property is not expressible as a Boolean |
121 | */ |
122 | IMG4_API_AVAILABLE_20180112 |
123 | typedef errno_t (*img4_environment_get_bool_t)( |
124 | const img4_environment_t *i4e, |
125 | bool *val, |
126 | const void *ctx); |
127 | |
128 | /*! |
129 | * @typedef img4_environment_get_uint32_t |
130 | * A function which obtains an unsigned 32-bit integer property from the host |
131 | * environment. |
132 | * |
133 | * @param val |
134 | * A pointer to storage in which the value will be written. |
135 | * |
136 | * @param ctx |
137 | * The context pointer supplied to {@link img4_init}. |
138 | * |
139 | * @result |
140 | * Upon successfully fetching the property value, zero should be returned. |
141 | * Otherwise, the following error codes should be returned: |
142 | * |
143 | * [ENOENT] The property does not exist in the environment |
144 | * [EFTYPE] The property is not expressible as an unsigned 32-bit integer |
145 | */ |
146 | IMG4_API_AVAILABLE_20180112 |
147 | typedef errno_t (*img4_environment_get_uint32_t)( |
148 | const img4_environment_t *i4e, |
149 | uint32_t *val, |
150 | const void *ctx); |
151 | |
152 | /*! |
153 | * @typedef img4_environment_get_uint64_t |
154 | * A function which obtains an unsigned 64-bit integer property from the host |
155 | * environment. |
156 | * |
157 | * @param val |
158 | * A pointer to storage in which the value will be written. |
159 | * |
160 | * @param ctx |
161 | * The context pointer supplied to {@link img4_init}. |
162 | * |
163 | * @result |
164 | * Upon successfully fetching the property value, zero should be returned. |
165 | * Otherwise, the following error codes should be returned: |
166 | * |
167 | * [ENOENT] The property does not exist in the environment |
168 | * [EFTYPE] The property is not expressible as an unsigned 64-bit |
169 | * integer |
170 | */ |
171 | IMG4_API_AVAILABLE_20180112 |
172 | typedef errno_t (*img4_environment_get_uint64_t)( |
173 | const img4_environment_t *i4e, |
174 | uint64_t *val, |
175 | const void *ctx); |
176 | |
177 | /*! |
178 | * @typedef img4_environment_get_data_t |
179 | * A function which obtains a property which is a raw sequence of bytes from the |
180 | * host environment. |
181 | * |
182 | * @param bytes |
183 | * A pointer to storage in which the value will be written. |
184 | * |
185 | * @param len |
186 | * A pointer to the length of the buffer referred to be {@link val}. Upon |
187 | * successful return, this storage should contain the number of bytes written. |
188 | * |
189 | * @param ctx |
190 | * The context pointer supplied to {@link img4_init}. |
191 | * |
192 | * @result |
193 | * Upon successfully fetching the property value, zero should be returned. |
194 | * Otherwise, the following error codes should be returned: |
195 | * |
196 | * [ENOENT] The property does not exist in the environment |
197 | * [EFTYPE] The property is not expressible as a raw sequence of bytes |
198 | * [ERANGE] The buffer was not large enough to hold the property |
199 | */ |
200 | IMG4_API_AVAILABLE_20180112 |
201 | typedef errno_t (*img4_environment_get_data_t)( |
202 | const img4_environment_t *i4e, |
203 | uint8_t *bytes, |
204 | uint32_t *len, |
205 | const void *ctx); |
206 | |
207 | /*! |
208 | * @struct _img4_environment |
209 | * A type describing a host environment. |
210 | * |
211 | * @property i4e_version |
212 | * The version of the environment structure. Pass |
213 | * {@link IMG4_ENVIRONMENT_VERSION}. |
214 | * |
215 | * @property i4e_name |
216 | * A human-readable description of the environment. |
217 | * |
218 | * @property i4e_crypto |
219 | * A pointer to a function which returns the crypto implementation for the |
220 | * environment. |
221 | * |
222 | * @property i4e_cert_epoch |
223 | * A pointer to a function which returns the certificate epoch for the |
224 | * environment. |
225 | * |
226 | * @property i4e_board_id |
227 | * A pointer to a function which returns the board identifier for the |
228 | * environment. |
229 | * |
230 | * @property i4e_chip_id |
231 | * A pointer to a function which returns the chip design identifier for the |
232 | * environment. |
233 | * |
234 | * @property i4e_ecid |
235 | * A pointer to a function which returns the unique chip identifier for the |
236 | * environment. |
237 | * |
238 | * @property i4e_security_domain |
239 | * A pointer to a function which returns the security domain for the |
240 | * environment. |
241 | * |
242 | * @property i4e_cert_prod |
243 | * A pointer to a function which returns the certificate production status for |
244 | * the environment. This indicates whether the environment's leaf certificate |
245 | * must be production or development. |
246 | * |
247 | * - true the environment's leaf certificate must be production |
248 | * - false the environment's leaf certificate may be development |
249 | * |
250 | * @property i4e_cert_security |
251 | * A pointer to a function which returns the certificate security mode for the |
252 | * environment. This indicates Whether the leaf certificate must be secure. |
253 | * |
254 | * @property i4e_ap_nonce_hash |
255 | * A pointer to a function which returns the hash of the AP nonce for the |
256 | * environment. |
257 | * |
258 | * @property i4e_prevent_mixnmatch |
259 | * A pointer to a function which returns whether the environment prevents mix- |
260 | * n-match. |
261 | * |
262 | * - true the environment disallows mix-n-match |
263 | * - false the environment allows mix-n-match |
264 | * |
265 | * @property i4e_boot_manifest_hash |
266 | * A pointer to a function which returns the hash of the manifest from which |
267 | * mix-n-match policy derives. |
268 | * |
269 | * @property i4e_eff_security |
270 | * A pointer to a function which returns the effective security mode for the |
271 | * environment. |
272 | * |
273 | * @property i4e_eff_prod |
274 | * A pointer to a function which returns the effective production status for the |
275 | * environment. |
276 | * |
277 | * @property i4e_ap_nonce_trust |
278 | * A pointer to a function which returns whether the AP nonce must be |
279 | * exclusively fetched from main memory. |
280 | * |
281 | * - true the AP nonce hash must be fetched from main memory exclusively; |
282 | * persistent storage is not trustworthy |
283 | * - false the AP nonce hash may be fetched from persistent storage |
284 | */ |
285 | struct _img4_environment { |
286 | img4_struct_version_t i4e_version; |
287 | const char *i4e_name; |
288 | img4_environment_get_crypto_t i4e_crypto; |
289 | img4_environment_get_uint32_t i4e_cert_epoch; |
290 | img4_environment_get_uint32_t i4e_board_id; |
291 | img4_environment_get_uint32_t i4e_chip_id; |
292 | img4_environment_get_uint64_t i4e_ecid; |
293 | img4_environment_get_uint32_t i4e_security_domain; |
294 | img4_environment_get_bool_t i4e_cert_prod; |
295 | img4_environment_get_bool_t i4e_cert_security; |
296 | img4_environment_get_data_t i4e_ap_nonce_hash; |
297 | img4_environment_get_bool_t i4e_prevent_mixnmatch; |
298 | img4_environment_get_data_t i4e_boot_manifest_hash; |
299 | img4_environment_get_bool_t i4e_eff_prod; |
300 | img4_environment_get_bool_t i4e_eff_security; |
301 | img4_environment_get_bool_t i4e_ap_nonce_trust; |
302 | } IMG4_API_AVAILABLE_20180112; |
303 | |
304 | /*! |
305 | * @const IMG4_ENVIRONMENT_PLATFORM |
306 | * The environment for the host that uses the default platform implementation to |
307 | * resolve the environment. |
308 | */ |
309 | IMG4_API_AVAILABLE_20180112 |
310 | OS_EXPORT |
311 | const struct _img4_environment _img4_environment_platform; |
312 | #define IMG4_ENVIRONMENT_PLATFORM (&_img4_environment_platform) |
313 | |
314 | #endif // __IMG4_ENVIRONMENT_H |
315 | |