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