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 */
23IMG4_API_AVAILABLE_20180112
24typedef 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 */
45IMG4_API_AVAILABLE_20180112
46typedef 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 */
58IMG4_API_AVAILABLE_20180112
59OS_EXPORT
60const 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 */
67IMG4_API_AVAILABLE_20180112
68OS_EXPORT
69const 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 */
76IMG4_API_AVAILABLE_20180112
77typedef 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 */
99IMG4_API_AVAILABLE_20180112
100typedef 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 */
122IMG4_API_AVAILABLE_20180112
123typedef 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 */
146IMG4_API_AVAILABLE_20180112
147typedef 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 */
171IMG4_API_AVAILABLE_20180112
172typedef 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 */
200IMG4_API_AVAILABLE_20180112
201typedef 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 */
285struct _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 */
309IMG4_API_AVAILABLE_20180112
310OS_EXPORT
311const struct _img4_environment _img4_environment_platform;
312#define IMG4_ENVIRONMENT_PLATFORM (&_img4_environment_platform)
313
314#endif // __IMG4_ENVIRONMENT_H
315