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