1 | /*! |
2 | * @header |
3 | * Supported chip environments. |
4 | */ |
5 | #ifndef __IMG4_CHIP_H |
6 | #define __IMG4_CHIP_H |
7 | |
8 | #ifndef __IMG4_INDIRECT |
9 | #error "Please #include <img4/firmware.h> instead of this file directly" |
10 | #endif // __IMG4_INDIRECT |
11 | |
12 | __BEGIN_DECLS |
13 | OS_ASSUME_NONNULL_BEGIN |
14 | OS_ASSUME_PTR_ABI_SINGLE_BEGIN |
15 | |
16 | /*! |
17 | * @typedef img4_chip_select_array_t |
18 | * A type representing a list of chips from which the implementation may select. |
19 | */ |
20 | IMG4_API_AVAILABLE_20200724 |
21 | typedef const img4_chip_t *_Nullable const *img4_chip_select_array_t; |
22 | |
23 | /*! |
24 | * @const IMG4_CHIP_INSTANCE_STRUCT_VERSION |
25 | * The version of the {@link img4_chip_instance_t} supported by the |
26 | * implementation. |
27 | */ |
28 | #define IMG4_CHIP_INSTANCE_STRUCT_VERSION (6u) |
29 | |
30 | /*! |
31 | * @typedef img4_chip_instance_omit_t |
32 | * A bitfield describing omitted identifiers from a chip instance. |
33 | * |
34 | * @const IMG4_CHIP_INSTANCE_OMIT_CEPO |
35 | * The chip instance has no epoch. |
36 | * |
37 | * @const IMG4_CHIP_INSTANCE_OMIT_BORD |
38 | * The chip instance has no board identifier. |
39 | * |
40 | * @const IMG4_CHIP_INSTANCE_OMIT_CHIP |
41 | * The chip instance has no chip identifier. |
42 | * |
43 | * @const IMG4_CHIP_INSTANCE_OMIT_SDOM |
44 | * The chip instance has no security domain. |
45 | * |
46 | * @const IMG4_CHIP_INSTANCE_OMIT_ECID |
47 | * The chip instance has no unique chip identifier. |
48 | * |
49 | * @const IMG4_CHIP_INSTANCE_OMIT_CPRO |
50 | * The chip instance has no certificate production status. |
51 | * |
52 | * @const IMG4_CHIP_INSTANCE_OMIT_CSEC |
53 | * The chip instance has no certificate security mode. |
54 | * |
55 | * @const IMG4_CHIP_INSTANCE_OMIT_EPRO |
56 | * The chip instance has no effective production status. |
57 | * |
58 | * @const IMG4_CHIP_INSTANCE_OMIT_ESEC |
59 | * The chip instance has no effective security mode. |
60 | * |
61 | * @const IMG4_CHIP_INSTANCE_OMIT_IUOU |
62 | * The chip instance has no internal-use-only-unit property. |
63 | * |
64 | * @const IMG4_CHIP_INSTANCE_OMIT_RSCH |
65 | * The chip instance has no research fusing state. |
66 | * |
67 | * @const IMG4_CHIP_INSTANCE_OMIT_EUOU |
68 | * The chip instance has no engineering-use-only-unit property. |
69 | * |
70 | * @const IMG4_CHIP_INSTANCE_OMIT_ESDM |
71 | * The chip instance has no extended security domain property. |
72 | * |
73 | * @const IMG4_CHIP_INSTANCE_OMIT_FPGT |
74 | * The chip instance has no factory pre-release global trust property. |
75 | * |
76 | * @const IMG4_CHIP_INSTANCE_OMIT_UDID |
77 | * The chip instance has no universal device identifier property. |
78 | * |
79 | * @const IMG4_CHIP_INSTANCE_OMIT_FCHP |
80 | * The chip instance has no cryptex chip identifier property. |
81 | * |
82 | * @const IMG4_CHIP_INSTANCE_OMIT_TYPE |
83 | * The chip instance has no cryptex type identifier property. |
84 | * |
85 | * @const IMG4_CHIP_INSTANCE_OMIT_STYP |
86 | * The chip instance has no cryptex subtype identifier property. |
87 | * |
88 | * @const IMG4_CHIP_INSTANCE_OMIT_CLAS |
89 | * The chip instance has no product class property. |
90 | */ |
91 | OS_CLOSED_OPTIONS(img4_chip_instance_omit, uint64_t, |
92 | IMG4_CHIP_INSTANCE_OMIT_CEPO = (1 << 0), |
93 | IMG4_CHIP_INSTANCE_OMIT_BORD = (1 << 1), |
94 | IMG4_CHIP_INSTANCE_OMIT_CHIP = (1 << 2), |
95 | IMG4_CHIP_INSTANCE_OMIT_SDOM = (1 << 3), |
96 | IMG4_CHIP_INSTANCE_OMIT_ECID = (1 << 4), |
97 | IMG4_CHIP_INSTANCE_OMIT_CPRO = (1 << 5), |
98 | IMG4_CHIP_INSTANCE_OMIT_CSEC = (1 << 6), |
99 | IMG4_CHIP_INSTANCE_OMIT_EPRO = (1 << 7), |
100 | IMG4_CHIP_INSTANCE_OMIT_ESEC = (1 << 8), |
101 | IMG4_CHIP_INSTANCE_OMIT_IUOU = (1 << 9), |
102 | IMG4_CHIP_INSTANCE_OMIT_RSCH = (1 << 10), |
103 | IMG4_CHIP_INSTANCE_OMIT_EUOU = (1 << 11), |
104 | IMG4_CHIP_INSTANCE_OMIT_ESDM = (1 << 12), |
105 | IMG4_CHIP_INSTANCE_OMIT_FPGT = (1 << 13), |
106 | IMG4_CHIP_INSTANCE_OMIT_UDID = (1 << 14), |
107 | IMG4_CHIP_INSTANCE_OMIT_FCHP = (1 << 15), |
108 | IMG4_CHIP_INSTANCE_OMIT_TYPE = (1 << 16), |
109 | IMG4_CHIP_INSTANCE_OMIT_STYP = (1 << 17), |
110 | IMG4_CHIP_INSTANCE_OMIT_CLAS = (1 << 18), |
111 | ); |
112 | |
113 | /*! |
114 | * @typedef img4_chip_instance_t |
115 | * An structure describing an instance of a chip. |
116 | * |
117 | * @field chid_version |
118 | * The version of the structure. Initialize to |
119 | * {@link IMG4_CHIP_INSTANCE_STRUCT_VERSION}. |
120 | * |
121 | * @field chid_chip_family |
122 | * The chip family of which this is an instance. |
123 | * |
124 | * @field chid_omit |
125 | * The identifiers which are absent from the chip instance. |
126 | * |
127 | * @field chid_cepo |
128 | * The certificate epoch of the chip instance. |
129 | * |
130 | * @field chid_bord |
131 | * The board identifier of the chip instance. |
132 | * |
133 | * @field chid_chip |
134 | * The chip identifier of the chip instance. |
135 | * |
136 | * @field chid_sdom |
137 | * The security domain of the chip instance. |
138 | * |
139 | * @field chid_ecid |
140 | * The unique chip identifier of the chip instance. |
141 | * |
142 | * @field chid_cpro |
143 | * The certificate production status of the chip instance. |
144 | * |
145 | * @field chid_csec |
146 | * The certificate security mode of the chip instance. |
147 | * |
148 | * @field chid_epro |
149 | * The effective production status of the chip instance. |
150 | * |
151 | * @field chid_esec |
152 | * The effective security mode of the chip instance. |
153 | * |
154 | * @field chid_iuou |
155 | * The internal use-only unit status of the chip instance. |
156 | * |
157 | * @field chid_rsch |
158 | * The research mode of the chip instance. |
159 | * |
160 | * @field chid_euou |
161 | * The engineering use-only unit status of the chip instance. |
162 | * |
163 | * Added in version 1 of the structure. |
164 | * |
165 | * @field chid_esdm |
166 | * The extended security domain of the chip instance. |
167 | * |
168 | * Added in version 3 of the structure. |
169 | * |
170 | * @field chid_fpgt |
171 | * The factory pre-release global trust status of the chip instance. |
172 | * |
173 | * Added in version 4 of the structure. |
174 | * |
175 | * @field chid_udid |
176 | * The universal device identifier of the chip instance. |
177 | * |
178 | * Added in version 5 of the structure. |
179 | * |
180 | * @const chid_fchp |
181 | * The cryptex chip identifier of the chip instance. |
182 | * |
183 | * Added in version 6 of the structure. |
184 | * |
185 | * @const chid_type |
186 | * The cryptex type identifier of the chip instance. |
187 | * |
188 | * Added in version 6 of the structure. |
189 | * |
190 | * @const chid_styp |
191 | * The cryptex subtype identifier of the chip instance. |
192 | * |
193 | * Added in version 6 of the structure. |
194 | * |
195 | * @field chid_clas |
196 | * The product class of the chip instance. |
197 | * |
198 | * Added in version 6 of the structure. |
199 | */ |
200 | IMG4_API_AVAILABLE_20200508 |
201 | typedef struct _img4_chip_instance { |
202 | img4_struct_version_t chid_version; |
203 | const img4_chip_t *chid_chip_family; |
204 | img4_chip_instance_omit_t chid_omit; |
205 | uint32_t chid_cepo; |
206 | uint32_t chid_bord; |
207 | uint32_t chid_chip; |
208 | uint32_t chid_sdom; |
209 | uint64_t chid_ecid; |
210 | bool chid_cpro; |
211 | bool chid_csec; |
212 | bool chid_epro; |
213 | bool chid_esec; |
214 | bool chid_iuou; |
215 | bool chid_rsch; |
216 | bool chid_euou; |
217 | uint32_t chid_esdm; |
218 | bool chid_fpgt; |
219 | img4_dgst_t chid_udid; |
220 | uint32_t chid_fchp; |
221 | uint32_t chid_type; |
222 | uint32_t chid_styp; |
223 | uint32_t chid_clas; |
224 | } img4_chip_instance_t; |
225 | |
226 | /*! |
227 | * @function IMG4_CHIP_INSTANCE_INIT |
228 | * A convenience initializer which can be used to initialize a chip instance to |
229 | * a given family. |
230 | * |
231 | * @param _family |
232 | * The family of chip. |
233 | * |
234 | * @result |
235 | * A fully-initialized structure of the appropriate version supported by the |
236 | * implementation. The resulting chip instance omits no identifiers. |
237 | */ |
238 | #define IMG4_CHIP_INSTANCE_INIT(_family) (img4_chip_instance_t){ \ |
239 | .chid_version = IMG4_CHIP_INSTANCE_STRUCT_VERSION, \ |
240 | .chid_chip_family = (_family), \ |
241 | .chid_omit = 0, \ |
242 | .chid_cepo = 0, \ |
243 | .chid_bord = 0, \ |
244 | .chid_chip = 0, \ |
245 | .chid_sdom = 0, \ |
246 | .chid_ecid = 0, \ |
247 | .chid_cpro = false, \ |
248 | .chid_csec = false, \ |
249 | .chid_epro = false, \ |
250 | .chid_esec = false, \ |
251 | .chid_iuou = false, \ |
252 | .chid_rsch = false, \ |
253 | .chid_euou = false, \ |
254 | .chid_esdm = 0, \ |
255 | .chid_fpgt = false, \ |
256 | .chid_udid = {0}, \ |
257 | .chid_fchp = 0, \ |
258 | .chid_type = 0, \ |
259 | .chid_styp = 0, \ |
260 | .chid_clas = 0, \ |
261 | } |
262 | |
263 | /*! |
264 | * @function img4_chip_init_from_buff |
265 | * Initializes a buffer as a chip object. |
266 | * |
267 | * @param buff |
268 | * A pointer to the storage to use for the chip object. |
269 | * |
270 | * @param len |
271 | * The size of the buffer. |
272 | * |
273 | * @discussion |
274 | * The caller is expected to pass a buffer that is "big enough". If the provided |
275 | * buffer is too small, the implementation will abort the caller. |
276 | * |
277 | * @example |
278 | * |
279 | * uint8_t _buff[IMG4_CHIP_SIZE_RECOMMENDED]; |
280 | * img4_chip_t *chip = NULL; |
281 | * |
282 | * chip = img4_chip_init_from_buff(_buff, sizeof(_buff)); |
283 | */ |
284 | #if !XNU_KERNEL_PRIVATE |
285 | IMG4_API_AVAILABLE_20200508 |
286 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 |
287 | img4_chip_t * |
288 | img4_chip_init_from_buff(void *__sized_by(len) buff, size_t len); |
289 | #else |
290 | #define img4_chip_init_from_buff (img4if->i4if_v7.chip_init_from_buff) |
291 | #endif |
292 | |
293 | /*! |
294 | * @function img4_chip_select_personalized_ap |
295 | * Returns the chip appropriate for personalized verification against the host |
296 | * AP. |
297 | * |
298 | * @result |
299 | * The personalized chip environment for the host which corresponds to its |
300 | * silicon identity. |
301 | */ |
302 | #if !XNU_KERNEL_PRIVATE |
303 | IMG4_API_AVAILABLE_20200508 |
304 | OS_EXPORT OS_WARN_RESULT |
305 | const img4_chip_t * |
306 | img4_chip_select_personalized_ap(void); |
307 | #else |
308 | #define img4_chip_select_personalized_ap(...) \ |
309 | (img4if->i4if_v7.chip_select_personalized_ap(__VA_ARGS__)) |
310 | #endif |
311 | |
312 | /*! |
313 | * @function img4_chip_select_personalized_sep |
314 | * Returns the chip appropriate for personalized verification against the host |
315 | * SEP. |
316 | * |
317 | * @result |
318 | * The personalized chip environment for the host's SEP which corresponds to its |
319 | * silicon identity. This will return NULL when called outside of the SEP |
320 | * runtime. |
321 | */ |
322 | #if !XNU_KERNEL_PRIVATE |
323 | IMG4_API_AVAILABLE_20211119 |
324 | OS_EXPORT OS_WARN_RESULT |
325 | const img4_chip_t *_Nullable |
326 | img4_chip_select_personalized_sep(void); |
327 | #else |
328 | #define img4_chip_select_personalized_sep(...) \ |
329 | (img4if->i4if_v16.chip_select_personalized_sep(__VA_ARGS__)) |
330 | #endif |
331 | |
332 | /*! |
333 | * @function img4_chip_select_categorized_ap |
334 | * Returns the chip appropriate for categorized verification against the host |
335 | * AP. |
336 | * |
337 | * @result |
338 | * The categorized chip environment for the host which corresponds to its |
339 | * silicon identity. If the host has no AP category defined for it, NULL will be |
340 | * returned. |
341 | * |
342 | * @discussion |
343 | * Categorized chip environments have been scuttled and were never used. Please |
344 | * remove all uses of this function. |
345 | */ |
346 | #if !XNU_KERNEL_PRIVATE |
347 | IMG4_API_AVAILABLE_20210305 |
348 | OS_EXPORT OS_WARN_RESULT |
349 | const img4_chip_t *_Nullable |
350 | img4_chip_select_categorized_ap(void); |
351 | #else |
352 | #define img4_chip_select_categorized_ap(...) \ |
353 | (img4if->i4if_v12.chip_select_categorized_ap(__VA_ARGS__)) |
354 | #endif |
355 | |
356 | /*! |
357 | * @function img4_chip_select_effective_ap |
358 | * Returns the chip appropriate for verification against the host AP. |
359 | * |
360 | * @result |
361 | * The currently enforced chip environment for the host. This interface is |
362 | * generally only useful on the AP. |
363 | */ |
364 | #if !XNU_KERNEL_PRIVATE |
365 | IMG4_API_AVAILABLE_20200508 |
366 | OS_EXPORT OS_WARN_RESULT |
367 | const img4_chip_t * |
368 | img4_chip_select_effective_ap(void); |
369 | #else |
370 | #define img4_chip_select_effective_ap(...) \ |
371 | (img4if->i4if_v7.chip_select_effective_ap(__VA_ARGS__)) |
372 | #endif |
373 | |
374 | /*! |
375 | * @function img4_chip_select_cryptex1_boot |
376 | * Returns the appropriate Cryptex1 boot chip environment for the currently- |
377 | * booted effective AP environment. |
378 | * |
379 | * @result |
380 | * The chip environment to use for verification. |
381 | */ |
382 | #if !XNU_KERNEL_PRIVATE |
383 | IMG4_API_AVAILABLE_20211126 |
384 | OS_EXPORT OS_WARN_RESULT |
385 | const img4_chip_t * |
386 | img4_chip_select_cryptex1_boot(void); |
387 | #else |
388 | #define img4_chip_select_cryptex1_boot(...) \ |
389 | (img4if->i4if_v17.chip_select_cryptex1_boot(__VA_ARGS__)) |
390 | #endif |
391 | |
392 | /*! |
393 | * @function img4_chip_select_cryptex1_preboot |
394 | * Returns the appropriate Cryptex1 pre-reboot chip environment for the |
395 | * currently-booted effective AP environment. |
396 | * |
397 | * @result |
398 | * The chip environment to use for verification. |
399 | */ |
400 | #if !XNU_KERNEL_PRIVATE |
401 | IMG4_API_AVAILABLE_20211126 |
402 | OS_EXPORT OS_WARN_RESULT |
403 | const img4_chip_t * |
404 | img4_chip_select_cryptex1_preboot(void); |
405 | #else |
406 | #define img4_chip_select_cryptex1_preboot(...) \ |
407 | (img4if->i4if_v17.chip_select_cryptex1_preboot(__VA_ARGS__)) |
408 | #endif |
409 | |
410 | /*! |
411 | * @function img4_chip_get_cryptex1_boot |
412 | * Returns the appropriate Cryptex1 boot chip environment associated with a |
413 | * given AP environment. |
414 | * |
415 | * @param chip |
416 | * The AP environment for which to obtain the associated Cryptex1 environment. |
417 | * |
418 | * @result |
419 | * The Cryptex1 chip environment associated with {@link chip}. If there is no |
420 | * Cryptex1 association, NULL is returned. |
421 | */ |
422 | #if !XNU_KERNEL_PRIVATE |
423 | IMG4_API_AVAILABLE_20220401 |
424 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 |
425 | const img4_chip_t *_Nullable |
426 | img4_chip_get_cryptex1_boot(const img4_chip_t *chip); |
427 | #else |
428 | #define img4_chip_get_cryptex1_boot(...) \ |
429 | (img4if->i4if_v18.chip_get_cryptex1_boot(__VA_ARGS__)) |
430 | #endif |
431 | |
432 | /*! |
433 | * @function img4_chip_get_cryptex1_boot_proposal |
434 | * Returns the appropriate Cryptex1 boot proposal chip environment associated |
435 | * with a given AP environment. |
436 | * |
437 | * @param chip |
438 | * The AP environment for which to obtain the associated Cryptex1 proposal |
439 | * environment. |
440 | * |
441 | * @result |
442 | * The Cryptex1 proposal chip environment associated with {@link chip}. If |
443 | * there is no Cryptex1 association, NULL is returned. |
444 | */ |
445 | #if !XNU_KERNEL_PRIVATE |
446 | IMG4_API_AVAILABLE_20220401 |
447 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 |
448 | const img4_chip_t *_Nullable |
449 | img4_chip_get_cryptex1_boot_proposal(const img4_chip_t *chip); |
450 | #else |
451 | #define img4_chip_get_cryptex1_boot_proposal(...) \ |
452 | (img4if->i4if_v18.chip_get_cryptex1_boot_proposal(__VA_ARGS__)) |
453 | #endif |
454 | |
455 | /*! |
456 | * @function img4_chip_instantiate |
457 | * Returns an instantiation of the given chip using the default runtime where |
458 | * necessary. |
459 | * |
460 | * @param chip |
461 | * The chip to instantiate. |
462 | * |
463 | * @param chip_instance |
464 | * Upon successful return, storage to be populated with the instantiated chip. |
465 | * Upon failure, the contents of this storage are undefined. |
466 | * |
467 | * @result |
468 | * Upon success, zero is returned. Otherwise, one of the following error codes |
469 | * will be returned: |
470 | * |
471 | * [EXDEV] There was an error querying the runtime's identity oracle |
472 | * [ENODATA] The expected property in the runtime's identity oracle was |
473 | * of an unexpected type |
474 | * [EOVERFLOW] The expected property in the runtime's identity oracle had |
475 | * a value that was too large to be represented in the |
476 | * expected type |
477 | */ |
478 | #if !XNU_KERNEL_PRIVATE |
479 | IMG4_API_AVAILABLE_20200508 |
480 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2 |
481 | errno_t |
482 | img4_chip_instantiate(const img4_chip_t *chip, |
483 | img4_chip_instance_t *chip_instance); |
484 | #else |
485 | #define img4_chip_instantiate(...) \ |
486 | (img4if->i4if_v7.chip_instantiate(__VA_ARGS__)) |
487 | #endif |
488 | |
489 | /*! |
490 | * @function img4_chip_custom |
491 | * Returns a custom chip derived from the given chip instance. The |
492 | * {@link chid_chip_family} field of the given instance will be used as a |
493 | * template from which to derive the new chip. |
494 | * |
495 | * @param chip_instance |
496 | * The instance of the custom chip. |
497 | * |
498 | * The memory referenced by this pointer must be static or otherwise guaranteed |
499 | * to be valid for the duration of the caller's use of the custom chip. |
500 | * |
501 | * @param chip |
502 | * A pointer to storage for the new custom chip. |
503 | * |
504 | * The memory referenced by this pointer must be static or otherwise guaranteed |
505 | * to be valid for the duration of the caller's use of the custom chip. |
506 | * |
507 | * This pointer should be obtained as the result of a call to |
508 | * {@link img4_chip_init_from_buff}. |
509 | * |
510 | * @result |
511 | * A new custom chip. |
512 | */ |
513 | #if !XNU_KERNEL_PRIVATE |
514 | IMG4_API_AVAILABLE_20200508 |
515 | OS_EXPORT OS_WARN_RESULT OS_NONNULL1 |
516 | const img4_chip_t * |
517 | img4_chip_custom(const img4_chip_instance_t *chip_instance, img4_chip_t *chip); |
518 | #else |
519 | #define img4_chip_custom(...) (img4if->i4if_v7.chip_custom(__VA_ARGS__)) |
520 | #endif |
521 | |
522 | OS_ASSUME_PTR_ABI_SINGLE_END |
523 | OS_ASSUME_NONNULL_END |
524 | __END_DECLS |
525 | |
526 | #endif // __IMG4_CHIP_H |
527 | |