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
13OS_ASSUME_NONNULL_BEGIN
14OS_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 */
20IMG4_API_AVAILABLE_20200724
21typedef 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 */
91OS_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 */
200IMG4_API_AVAILABLE_20200508
201typedef 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
285IMG4_API_AVAILABLE_20200508
286OS_EXPORT OS_WARN_RESULT OS_NONNULL1
287img4_chip_t *
288img4_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
303IMG4_API_AVAILABLE_20200508
304OS_EXPORT OS_WARN_RESULT
305const img4_chip_t *
306img4_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
323IMG4_API_AVAILABLE_20211119
324OS_EXPORT OS_WARN_RESULT
325const img4_chip_t *_Nullable
326img4_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
347IMG4_API_AVAILABLE_20210305
348OS_EXPORT OS_WARN_RESULT
349const img4_chip_t *_Nullable
350img4_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
365IMG4_API_AVAILABLE_20200508
366OS_EXPORT OS_WARN_RESULT
367const img4_chip_t *
368img4_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
383IMG4_API_AVAILABLE_20211126
384OS_EXPORT OS_WARN_RESULT
385const img4_chip_t *
386img4_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
401IMG4_API_AVAILABLE_20211126
402OS_EXPORT OS_WARN_RESULT
403const img4_chip_t *
404img4_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
423IMG4_API_AVAILABLE_20220401
424OS_EXPORT OS_WARN_RESULT OS_NONNULL1
425const img4_chip_t *_Nullable
426img4_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
446IMG4_API_AVAILABLE_20220401
447OS_EXPORT OS_WARN_RESULT OS_NONNULL1
448const img4_chip_t *_Nullable
449img4_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
479IMG4_API_AVAILABLE_20200508
480OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
481errno_t
482img4_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
514IMG4_API_AVAILABLE_20200508
515OS_EXPORT OS_WARN_RESULT OS_NONNULL1
516const img4_chip_t *
517img4_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
522OS_ASSUME_PTR_ABI_SINGLE_END
523OS_ASSUME_NONNULL_END
524__END_DECLS
525
526#endif // __IMG4_CHIP_H
527