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
16OS_ASSUME_NONNULL_BEGIN
17OS_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 */
33IMAGE4_API_AVAILABLE_SPRING_2024
34OS_EXPORT
35const image4_trust_evaluation_t _image4_trust_evaluation_exec;
36#define IMAGE4_TRUST_EVALUATION_EXEC (&_image4_trust_evaluation_exec)
37IMAGE4_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 */
56IMAGE4_API_AVAILABLE_SPRING_2024
57OS_EXPORT
58const image4_trust_evaluation_t _image4_trust_evaluation_preflight;
59#define IMAGE4_TRUST_EVALUATION_PREFLIGHT (&_image4_trust_evaluation_preflight)
60IMAGE4_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 */
74IMAGE4_API_AVAILABLE_SPRING_2024
75OS_EXPORT
76const image4_trust_evaluation_t _image4_trust_evaluation_sign;
77#define IMAGE4_TRUST_EVALUATION_SIGN (&_image4_trust_evaluation_sign)
78IMAGE4_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 */
101IMAGE4_API_AVAILABLE_SPRING_2024
102OS_EXPORT
103const image4_trust_evaluation_t _image4_trust_evaluation_boot;
104#define IMAGE4_TRUST_EVALUATION_BOOT (&_image4_trust_evaluation_boot)
105IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_boot);
106
107OS_ASSUME_PTR_ABI_SINGLE_END
108OS_ASSUME_NONNULL_END
109__END_DECLS
110
111#endif // __IMAGE4_API_TRUST_EVALUATION_H
112