EXTERNAL_HEADERS/img4/chip.h

   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 #if IMG4_TAPI
  13 #include "tapi.h"
  14 #endif
  15
  16 OS_ASSUME_NONNULL_BEGIN
  17
  18 /*!
  19  * @typedef img4_chip_t
  20  * An opaque type describing a destination chip environment for the firmware
  21  * image.
  22  */
  23 IMG4_API_AVAILABLE_20200508
  24 typedef struct _img4_chip img4_chip_t;
  25
  26 /*!
  27  * @typedef img4_chip_select_array_t
  28  * A type representing a list of chips from which the implementation may select.
  29  */
  30 IMG4_API_AVAILABLE_20200724
  31 typedef const img4_chip_t *_Nullable const *img4_chip_select_array_t;
  32
  33 /*!
  34  * @const IMG4_CHIP_INSTANCE_STRUCT_VERSION
  35  * The version of the {@link img4_chip_instance_t} supported by the
  36  * implementation.
  37  */
  38 #define IMG4_CHIP_INSTANCE_STRUCT_VERSION (1u)
  39
  40 /*!
  41  * @typedef img4_chip_instance_omit_t
  42  * A bitfield describing omitted identifiers from a chip instance.
  43  *
  44  * @const IMG4_CHIP_INSTANCE_OMIT_CEPO
  45  * The chip instance has no epoch.
  46  *
  47  * @const IMG4_CHIP_INSTANCE_OMIT_BORD
  48  * The chip instance has no board identifier.
  49  *
  50  * @const IMG4_CHIP_INSTANCE_OMIT_CHIP
  51  * The chip instance has no chip identifier.
  52  *
  53  * @const IMG4_CHIP_INSTANCE_OMIT_SDOM
  54  * The chip instance has no security domain.
  55  *
  56  * @const IMG4_CHIP_INSTANCE_OMIT_ECID
  57  * The chip instance has no unique chip identifier.
  58  *
  59  * @const IMG4_CHIP_INSTANCE_OMIT_CPRO
  60  * The chip instance has no certificate production status.
  61  *
  62  * @const IMG4_CHIP_INSTANCE_OMIT_CSEC
  63  * The chip instance has no certificate security mode.
  64  *
  65  * @const IMG4_CHIP_INSTANCE_OMIT_EPRO
  66  * The chip instance has no effective production status.
  67  *
  68  * @const IMG4_CHIP_INSTANCE_OMIT_ESEC
  69  * The chip instance has no effective security mode.
  70  *
  71  * @const IMG4_CHIP_INSTANCE_OMIT_IUOU
  72  * The chip instance has no internal-use-only-unit property.
  73  *
  74  * @const IMG4_CHIP_INSTANCE_OMIT_RSCH
  75  * The chip instance has no research fusing state.
  76  *
  77  * @const IMG4_CHIP_INSTANCE_OMIT_EUOU
  78  * The chip instance has no engineering-use-only-unit property.
  79  */
  80 OS_CLOSED_OPTIONS(img4_chip_instance_omit, uint64_t,
  81         IMG4_CHIP_INSTANCE_OMIT_CEPO = (1 << 0),
  82         IMG4_CHIP_INSTANCE_OMIT_BORD = (1 << 1),
  83         IMG4_CHIP_INSTANCE_OMIT_CHIP = (1 << 2),
  84         IMG4_CHIP_INSTANCE_OMIT_SDOM = (1 << 3),
  85         IMG4_CHIP_INSTANCE_OMIT_ECID = (1 << 4),
  86         IMG4_CHIP_INSTANCE_OMIT_CPRO = (1 << 5),
  87         IMG4_CHIP_INSTANCE_OMIT_CSEC = (1 << 6),
  88         IMG4_CHIP_INSTANCE_OMIT_EPRO = (1 << 7),
  89         IMG4_CHIP_INSTANCE_OMIT_ESEC = (1 << 8),
  90         IMG4_CHIP_INSTANCE_OMIT_IUOU = (1 << 9),
  91         IMG4_CHIP_INSTANCE_OMIT_RSCH = (1 << 10),
  92         IMG4_CHIP_INSTANCE_OMIT_EUOU = (1 << 11),
  93 );
  94
  95 /*!
  96  * @typedef img4_chip_instance_t
  97  * An structure describing an instance of a chip.
  98  *
  99  * @field chid_version
 100  * The version of the structure. Initialize to
 101  * {@link IMG4_CHIP_INSTANCE_STRUCT_VERSION}.
 102  *
 103  * @field chid_chip_family
 104  * The chip family of which this is an instance.
 105  *
 106  * @field chid_omit
 107  * The identifiers which are absent from the chip instance.
 108  *
 109  * @field chid_cepo
 110  * The certificate epoch of the chip instance.
 111  *
 112  * @field chid_bord
 113  * The board identifier of the chip instance.
 114  *
 115  * @field chid_chip
 116  * The chip identifier of the chip instance.
 117  *
 118  * @field chid_sdom
 119  * The security domain of the chip instance.
 120  *
 121  * @field chid_ecid
 122  * The unique chip identifier of the chip instance.
 123  *
 124  * @field chid_cpro
 125  * The certificate production status of the chip instance.
 126  *
 127  * @field chid_csec
 128  * The certificate security mode of the chip instance.
 129  *
 130  * @field chid_epro
 131  * The effective production status of the chip instance.
 132  *
 133  * @field chid_esec
 134  * The effective security mode of the chip instance.
 135  *
 136  * @field chid_iuou
 137  * The internal use-only unit status of the chip instance.
 138  *
 139  * @field chid_rsch
 140  * The research mode of the chip instance.
 141  *
 142  * @field chid_euou
 143  * The engineering use-only unit status of the chip instance.
 144  *
 145  * Added in version 1 of the structure.
 146  */
 147 IMG4_API_AVAILABLE_20200508
 148 typedef struct _img4_chip_instance {
 149         img4_struct_version_t chid_version;
 150         const img4_chip_t *chid_chip_family;
 151         img4_chip_instance_omit_t chid_omit;
 152         uint32_t chid_cepo;
 153         uint32_t chid_bord;
 154         uint32_t chid_chip;
 155         uint32_t chid_sdom;
 156         uint64_t chid_ecid;
 157         bool chid_cpro;
 158         bool chid_csec;
 159         bool chid_epro;
 160         bool chid_esec;
 161         bool chid_iuou;
 162         bool chid_rsch;
 163         bool chid_euou;
 164 } img4_chip_instance_t;
 165
 166 /*!
 167  * @const IMG4_CHIP_AP_SHA1
 168  * The Application Processor on an Apple ARM SoC with an embedded sha1
 169  * certifcate chain.
 170  *
 171  * This chip environment represents one unique instance of such a chip.
 172  */
 173 #if !XNU_KERNEL_PRIVATE
 174 IMG4_API_AVAILABLE_20200508
 175 OS_EXPORT
 176 const img4_chip_t _img4_chip_ap_sha1;
 177 #define IMG4_CHIP_AP_SHA1 (&_img4_chip_ap_sha1)
 178 #else
 179 #define IMG4_CHIP_AP_SHA1 (img4if->i4if_v7.chip_ap_sha1)
 180 #endif
 181
 182 /*!
 183  * @const IMG4_CHIP_AP_SHA2_384
 184  * The Application Processor on an Apple ARM SoC with an embedded sha2-384
 185  * certifcate chain.
 186  *
 187  * This chip environment represents one unique instance of such a chip.
 188  */
 189 #if !XNU_KERNEL_PRIVATE
 190 IMG4_API_AVAILABLE_20200508
 191 OS_EXPORT
 192 const img4_chip_t _img4_chip_ap_sha2_384;
 193 #define IMG4_CHIP_AP_SHA2_384 (&_img4_chip_ap_sha2_384)
 194 #else
 195 #define IMG4_CHIP_AP_SHA2_384 (img4if->i4if_v7.chip_ap_sha2_384)
 196 #endif
 197
 198 /*!
 199  * @const IMG4_CHIP_AP_HYBRID
 200  * An Intel x86 processor whose chain of trust is rooted in an
 201  * {@link IMG4_CHIP_AP_SHA2_384} environment. Firmwares executed on this chip
 202  * are authenticated against the characteristics of the corresponding AP chip
 203  * environment.
 204  *
 205  * This chip environment represents one unique instance of such a chip pair.
 206  */
 207 #if !XNU_KERNEL_PRIVATE
 208 IMG4_API_AVAILABLE_20200508
 209 OS_EXPORT
 210 const img4_chip_t _img4_chip_ap_hybrid;
 211 #define IMG4_CHIP_AP_HYBRID (&_img4_chip_ap_hybrid)
 212 #else
 213 #define IMG4_CHIP_AP_HYBRID (img4if->i4if_v7.chip_ap_hybrid)
 214 #endif
 215
 216 /*!
 217  * @const IMG4_CHIP_AP_REDUCED
 218  * An Application Processor on an Apple ARM SoC operating in a reduced security
 219  * configuration.
 220  *
 221  * This chip cannot be uniquely identified.
 222  */
 223 #if !XNU_KERNEL_PRIVATE
 224 IMG4_API_AVAILABLE_20200508
 225 OS_EXPORT
 226 const img4_chip_t _img4_chip_ap_reduced;
 227 #define IMG4_CHIP_AP_REDUCED (&_img4_chip_ap_reduced)
 228 #else
 229 #define IMG4_CHIP_AP_REDUCED (img4if->i4if_v7.chip_ap_reduced)
 230 #endif
 231
 232 /*!
 233  * @const IMG4_CHIP_AP_PERMISSIVE
 234  * An Application Processor on an Apple ARM SoC operating with no secure boot
 235  * enforcement.
 236  *
 237  * This chip cannot be uniquely identified.
 238  */
 239 #if !XNU_KERNEL_PRIVATE
 240 IMG4_API_AVAILABLE_20200508
 241 OS_EXPORT
 242 const img4_chip_t _img4_chip_ap_permissive;
 243 #define IMG4_CHIP_AP_PERMISSIVE (&_img4_chip_ap_permissive)
 244 #else
 245 #define IMG4_CHIP_AP_PERMISSIVE (img4if->i4if_v8.chip_ap_permissive)
 246 #endif
 247
 248 /*!
 249  * @const IMG4_CHIP_AP_HYBRID_MEDIUM
 250  * An Intel x86 processor whose chain of trust is rooted in an
 251  * {@link IMG4_CHIP_AP_SHA2_384} environment and is operating in a "medium
 252  * security" mode due to a user-approved security degradation.
 253  *
 254  * This chip cannot be uniquely identified.
 255  */
 256 #if !XNU_KERNEL_PRIVATE
 257 IMG4_API_AVAILABLE_20200508
 258 OS_EXPORT
 259 const img4_chip_t _img4_chip_ap_hybrid_medium;
 260 #define IMG4_CHIP_AP_HYBRID_MEDIUM (&_img4_chip_ap_hybrid_medium)
 261 #else
 262 #define IMG4_CHIP_AP_HYBRID_MEDIUM (img4if->i4if_v8.chip_ap_hybrid_medium)
 263 #endif
 264
 265 /*!
 266  * @const IMG4_CHIP_AP_HYBRID_RELAXED
 267  * An Intel x86 processor whose chain of trust is rooted in an
 268  * {@link IMG4_CHIP_AP_SHA2_384} environment and is operating with no secure
 269  * boot enforcement due to a user-approved security degradation.
 270  *
 271  * This chip cannot be uniquely identified.
 272  */
 273 #if !XNU_KERNEL_PRIVATE
 274 IMG4_API_AVAILABLE_20200508
 275 OS_EXPORT
 276 const img4_chip_t _img4_chip_ap_hybrid_relaxed;
 277 #define IMG4_CHIP_AP_HYBRID_RELAXED (&_img4_chip_ap_hybrid_relaxed)
 278 #else
 279 #define IMG4_CHIP_AP_HYBRID_RELAXED (img4if->i4if_v8.chip_ap_hybrid_relaxed)
 280 #endif
 281
 282 /*!
 283  * @const IMG4_CHIP_AP_SOFTWARE_FF00
 284  * A software-defined chip environment whose firmwares are executed on any
 285  * Application Processor on an Apple ARM SoC. The firmwares are loadable trust
 286  * caches shipped with OTA update brains.
 287  *
 288  * This chip cannot be uniquely identified.
 289  */
 290 #if !XNU_KERNEL_PRIVATE
 291 IMG4_API_AVAILABLE_20200508
 292 OS_EXPORT
 293 const img4_chip_t _img4_chip_ap_software_ff00;
 294 #define IMG4_CHIP_AP_SOFTWARE_FF00 (&_img4_chip_ap_software_ff00)
 295 #else
 296 #define IMG4_CHIP_AP_SOFTWARE_FF00 (img4if->i4if_v7.chip_ap_software_ff00)
 297 #endif
 298
 299 /*!
 300  * @const IMG4_CHIP_AP_SOFTWARE_FF01
 301  * A software-defined chip environment whose firmwares are executed on any
 302  * Application Processor on an Apple ARM SoC. The firmwares are loadable trust
 303  * caches which are shipped in the Install Assistant and loaded by an
 304  * unprivileged trampoline.
 305  *
 306  * This chip cannot be uniquely identified.
 307  */
 308 #if !XNU_KERNEL_PRIVATE
 309 IMG4_API_AVAILABLE_20200508
 310 OS_EXPORT
 311 const img4_chip_t _img4_chip_ap_software_ff01;
 312 #define IMG4_CHIP_AP_SOFTWARE_FF01 (&_img4_chip_ap_software_ff01)
 313 #else
 314 #define IMG4_CHIP_AP_SOFTWARE_FF01 (img4if->i4if_v7.chip_ap_software_ff01)
 315 #endif
 316
 317 /*!
 318  * @const IMG4_CHIP_X86
 319  * An Intel x86 processor which cannot be uniquely identified.
 320  */
 321 #if !XNU_KERNEL_PRIVATE
 322 IMG4_API_AVAILABLE_20200508
 323 OS_EXPORT
 324 const img4_chip_t _img4_chip_x86;
 325 #define IMG4_CHIP_X86 (&_img4_chip_x86)
 326 #else
 327 #define IMG4_CHIP_X86 (img4if->i4if_v7.chip_x86)
 328 #endif
 329
 330 /*!
 331  * @const IMG4_CHIP_X86_SOFTWARE_8012
 332  * A software-defined chip environment describing a virtualized x86 processor.
 333  * Since the virtual machine is at the mercy of the VM, support for any sort of
 334  * chip identity may not be available. Therefore this environment is returned
 335  * from {@link img4_chip_select_personalized_ap} and
 336  * {@link img4_chip_select_effective_ap} when it is called on a virtual machine
 337  * so that the appropriate chip environment is present entirely in software.
 338  *
 339  * This environment provides an equivalent software identity to that of
 340  * the {@link IMG4_CHIP_X86} chip environment on non-Gibraltar Macs.
 341  *
 342  * @discussion
 343  * Do not use this environment directly.
 344  */
 345 #if !XNU_KERNEL_PRIVATE
 346 IMG4_API_AVAILABLE_20200508
 347 OS_EXPORT
 348 const img4_chip_t _img4_chip_x86_software_8012;
 349 #define IMG4_CHIP_X86_SOFTWARE_8012 (&_img4_chip_x86_software_8012)
 350 #else
 351 #define IMG4_CHIP_X86_SOFTWARE_8012 (img4if->i4if_v7.chip_x86_software_8012)
 352 #endif
 353
 354 /*!
 355  * @function img4_chip_init_from_buff
 356  * Initializes a buffer as a chip object.
 357  *
 358  * @param buff
 359  * A pointer to the storage to use for the chip object.
 360  *
 361  * @param len
 362  * The size of the buffer.
 363  *
 364  * @discussion
 365  * The caller is expected to pass a buffer that is "big enough". If the provided
 366  * buffer is too small, the implementation will abort the caller.
 367  *
 368  * @example
 369  *
 370  *     uint8_t _buff[IMG4_CHIP_SIZE_RECOMMENDED];
 371  *     img4_chip_t *chip = NULL;
 372  *
 373  *     chip = img4_chip_init_from_buff(_buff, sizeof(_buff));
 374  */
 375 #if !XNU_KERNEL_PRIVATE
 376 IMG4_API_AVAILABLE_20200508
 377 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 378 img4_chip_t *
 379 img4_chip_init_from_buff(void *buff, size_t len);
 380 #else
 381 #define img4_chip_init_from_buff (img4if->i4if_v7.chip_init_from_buff)
 382 #endif
 383
 384 /*!
 385  * @function img4_chip_select_personalized_ap
 386  * Returns the chip appropriate for personalized verification against the host
 387  * AP.
 388  *
 389  * @result
 390  * The personalized chip environment for the host which corresponds to its
 391  * silicon identity.
 392  */
 393 #if !XNU_KERNEL_PRIVATE
 394 IMG4_API_AVAILABLE_20200508
 395 OS_EXPORT OS_WARN_RESULT
 396 const img4_chip_t *
 397 img4_chip_select_personalized_ap(void);
 398 #else
 399 #define img4_chip_select_personalized_ap(...) \
 400                 (img4if->i4if_v7.chip_select_personalized_ap(__VA_ARGS__))
 401 #endif
 402
 403 /*!
 404  * @function img4_chip_select_effective_ap
 405  * Returns the chip appropriate for verification against the host AP.
 406  *
 407  * @result
 408  * The currently enforced chip environment for the host. This interface is
 409  * generally only useful on the AP.
 410  */
 411 #if !XNU_KERNEL_PRIVATE
 412 IMG4_API_AVAILABLE_20200508
 413 OS_EXPORT OS_WARN_RESULT
 414 const img4_chip_t *
 415 img4_chip_select_effective_ap(void);
 416 #else
 417 #define img4_chip_select_effective_ap(...) \
 418                 (img4if->i4if_v7.chip_select_effective_ap(__VA_ARGS__))
 419 #endif
 420
 421 /*!
 422  * @function img4_chip_instantiate
 423  * Returns an instantiation of the given chip using the default runtime where
 424  * necessary.
 425  *
 426  * @param chip
 427  * The chip to instantiate.
 428  *
 429  * @param chip_instance
 430  * Upon successful return, storage to be populated with the instantiated chip.
 431  * Upon failure, the contents of this storage are undefined.
 432  *
 433  * @result
 434  * Upon success, zero is returned. Otherwise, one of the following error codes
 435  * will be returned:
 436  *
 437  *     [EXDEV]       There was an error querying the runtime's identity oracle
 438  *     [ENODATA]     The expected property in the runtime's identity oracle was
 439  *                   of an unexpected type
 440  *     [EOVERFLOW]   The expected property in the runtime's identity oracle had
 441  *                   a value that was too large to be represented in the
 442  *                   expected type
 443  */
 444 #if !XNU_KERNEL_PRIVATE
 445 IMG4_API_AVAILABLE_20200508
 446 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
 447 errno_t
 448 img4_chip_instantiate(const img4_chip_t *chip,
 449                 img4_chip_instance_t *chip_instance);
 450 #else
 451 #define img4_chip_instantiate(...) \
 452                 (img4if->i4if_v7.chip_instantiate(__VA_ARGS__))
 453 #endif
 454
 455 /*!
 456  * @function img4_chip_custom
 457  * Returns a custom chip derived from the given chip instance. The
 458  * {@link chid_chip_family} field of the given instance will be used as a
 459  * template from which to derive the new chip.
 460  *
 461  * @param chip_instance
 462  * The instance of the custom chip.
 463  *
 464  * The memory referenced by this pointer must be static or otherwise guaranteed
 465  * to be valid for the duration of the caller's use of the custom chip.
 466  *
 467  * @param chip
 468  * A pointer to storage for the new custom chip.
 469  *
 470  * The memory referenced by this pointer must be static or otherwise guaranteed
 471  * to be valid for the duration of the caller's use of the custom chip.
 472  *
 473  * This pointer should be obtained as the result of a call to
 474  * {@link img4_chip_init_from_buff}.
 475  *
 476  * @result
 477  * A new custom chip.
 478  */
 479 #if !XNU_KERNEL_PRIVATE
 480 IMG4_API_AVAILABLE_20200508
 481 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 482 const img4_chip_t *
 483 img4_chip_custom(const img4_chip_instance_t *chip_instance, img4_chip_t *chip);
 484 #else
 485 #define img4_chip_custom(...) (img4if->i4if_v7.chip_custom(__VA_ARGS__))
 486 #endif
 487
 488 OS_ASSUME_NONNULL_END
 489
 490 #endif // __IMG4_CHIP_H