1 | /*! |
2 | * @header |
3 | * Encapsulation which describes an Image4 trust evaluation procedure. The type |
4 | * of procedure impacts the result delivered to the |
5 | * {@link image4_trust_evaluation_result_t}. |
6 | * |
7 | * All trust evaluations require a manifest to be present in the trust object. |
8 | */ |
9 | #ifndef __IMAGE4_API_TRUST_EVALUATION_H |
10 | #define __IMAGE4_API_TRUST_EVALUATION_H |
11 | |
12 | #include <image4/image4.h> |
13 | #include <image4/types.h> |
14 | |
15 | __BEGIN_DECLS |
16 | OS_ASSUME_NONNULL_BEGIN |
17 | OS_ASSUME_PTR_ABI_SINGLE_BEGIN |
18 | |
19 | /*! |
20 | * @const IMAGE4_TRUST_EVALUATION_EXEC |
21 | * The trust evaluation is intended to execute firmware in the designated |
22 | * environment. This is to be used for either first- or second-stage boots. |
23 | * |
24 | * This type of trust evaluation requires a payload. |
25 | * |
26 | * @section Trust Evaluation Result |
27 | * Upon successful evaluation, the result is a pointer to the unwrapped Image4 |
28 | * payload bytes. |
29 | * |
30 | * @discussion |
31 | * This trust evaluation is supported on all targets. |
32 | */ |
33 | IMAGE4_API_AVAILABLE_SPRING_2024 |
34 | OS_EXPORT |
35 | const image4_trust_evaluation_t _image4_trust_evaluation_exec; |
36 | #define IMAGE4_TRUST_EVALUATION_EXEC (&_image4_trust_evaluation_exec) |
37 | IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_exec); |
38 | |
39 | /*! |
40 | * @const IMAGE4_TRUST_EVALUATION_PREFLIGHT |
41 | * The trust evaluation is intended to preflight a manifest to verify that it is |
42 | * likely to be accepted during a boot trust evaluation in the future. This is |
43 | * a best effort evaluation, and depending on the environment, certain |
44 | * enforcement policies may be relaxed due to the relevant information not being |
45 | * available. |
46 | * |
47 | * This type of trust evaluation does not require a payload. |
48 | * |
49 | * @section Trust Evaluation Result |
50 | * The result is an error code indicating whether the manifest is likely to be |
51 | * accepted by the environment. |
52 | * |
53 | * @discussion |
54 | * This type of trust evaluation is not supported on all targets. |
55 | */ |
56 | IMAGE4_API_AVAILABLE_SPRING_2024 |
57 | OS_EXPORT |
58 | const image4_trust_evaluation_t _image4_trust_evaluation_preflight; |
59 | #define IMAGE4_TRUST_EVALUATION_PREFLIGHT (&_image4_trust_evaluation_preflight) |
60 | IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_preflight); |
61 | |
62 | /*! |
63 | * @const IMAGE4_TRUST_EVALUATION_SIGN |
64 | * The trust evaluation is intended to facilitate counter-signing the manifest. |
65 | * |
66 | * @section Trust Evaluation Result |
67 | * Upon successful evaluation, the result is a pointer to the digest of the |
68 | * manifest. The digest is computed using the algorithm specified by the |
69 | * environment. |
70 | * |
71 | * @discussion |
72 | * This type of trust evaluation is not supported on all targets. |
73 | */ |
74 | IMAGE4_API_AVAILABLE_SPRING_2024 |
75 | OS_EXPORT |
76 | const image4_trust_evaluation_t _image4_trust_evaluation_sign; |
77 | #define IMAGE4_TRUST_EVALUATION_SIGN (&_image4_trust_evaluation_sign) |
78 | IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_sign); |
79 | |
80 | /*! |
81 | * @const IMAGE4_TRUST_EVALUATION_BOOT |
82 | * The trust evaluation is intended to bootstrap a subsequent trust evaluation |
83 | * in a chain of trust. The ultimate purpose of the chain of trust must be to |
84 | * either preflight a manifest or sign it. |
85 | * |
86 | * This type of trust evaluation does not require a payload. |
87 | * |
88 | * @section Trust Evaluation Result |
89 | * This type of trust evaluation is not intended to be performed directly by way |
90 | * of {@link image4_trust_evaluate}. It is instead intended to create a trust |
91 | * object which can be used as a previous stage of boot for another trust object |
92 | * by way of {@link image4_trust_set_booter}. |
93 | * |
94 | * However, if the caller wishes to perform a boot trust evaluation directly, |
95 | * then the trust evaluation result equivalent to that of |
96 | * {@link IMAGE4_TRUST_EVALUATION_SIGN}. |
97 | * |
98 | * @discussion |
99 | * This trust evaluation is supported on all targets. |
100 | */ |
101 | IMAGE4_API_AVAILABLE_SPRING_2024 |
102 | OS_EXPORT |
103 | const image4_trust_evaluation_t _image4_trust_evaluation_boot; |
104 | #define IMAGE4_TRUST_EVALUATION_BOOT (&_image4_trust_evaluation_boot) |
105 | IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_boot); |
106 | |
107 | OS_ASSUME_PTR_ABI_SINGLE_END |
108 | OS_ASSUME_NONNULL_END |
109 | __END_DECLS |
110 | |
111 | #endif // __IMAGE4_API_TRUST_EVALUATION_H |
112 | |