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