1 /* 2 * Copyright © 2017-2024 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 /*! 29 * @header 30 * Encapsulation which describes an Image4 trust evaluation procedure. The type 31 * of procedure impacts the result delivered to the 32 * {@link image4_trust_evaluation_result_t}. 33 * 34 * All trust evaluations require a manifest to be present in the trust object. 35 */ 36 #ifndef __IMAGE4_API_TRUST_EVALUATION_H 37 #define __IMAGE4_API_TRUST_EVALUATION_H 38 39 #include <image4/image4.h> 40 #include <image4/types.h> 41 42 __BEGIN_DECLS 43 OS_ASSUME_NONNULL_BEGIN 44 OS_ASSUME_PTR_ABI_SINGLE_BEGIN 45 46 /*! 47 * @const IMAGE4_TRUST_EVALUATION_EXEC 48 * The trust evaluation is intended to execute firmware in the designated 49 * environment. This is to be used for either first- or second-stage boots. 50 * 51 * This type of trust evaluation requires a payload. 52 * 53 * @section Trust Evaluation Result 54 * Upon successful evaluation, the result is a pointer to the unwrapped Image4 55 * payload bytes. 56 * 57 * @discussion 58 * This trust evaluation is supported on all targets. 59 */ 60 IMAGE4_API_AVAILABLE_SPRING_2024 61 OS_EXPORT 62 const image4_trust_evaluation_t _image4_trust_evaluation_exec; 63 #define IMAGE4_TRUST_EVALUATION_EXEC (&_image4_trust_evaluation_exec) 64 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_exec); 65 66 /*! 67 * @const IMAGE4_TRUST_EVALUATION_PREFLIGHT 68 * The trust evaluation is intended to preflight a manifest to verify that it is 69 * likely to be accepted during a boot trust evaluation in the future. This is 70 * a best effort evaluation, and depending on the environment, certain 71 * enforcement policies may be relaxed due to the relevant information not being 72 * available. 73 * 74 * This type of trust evaluation does not require a payload. 75 * 76 * @section Trust Evaluation Result 77 * The result is an error code indicating whether the manifest is likely to be 78 * accepted by the environment. 79 * 80 * @discussion 81 * This type of trust evaluation is not supported on all targets. 82 */ 83 IMAGE4_API_AVAILABLE_SPRING_2024 84 OS_EXPORT 85 const image4_trust_evaluation_t _image4_trust_evaluation_preflight; 86 #define IMAGE4_TRUST_EVALUATION_PREFLIGHT (&_image4_trust_evaluation_preflight) 87 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_preflight); 88 89 /*! 90 * @const IMAGE4_TRUST_EVALUATION_SIGN 91 * The trust evaluation is intended to facilitate counter-signing the manifest. 92 * 93 * @section Trust Evaluation Result 94 * Upon successful evaluation, the result is a pointer to the digest of the 95 * manifest. The digest is computed using the algorithm specified by the 96 * environment. 97 * 98 * @discussion 99 * This type of trust evaluation is not supported on all targets. 100 */ 101 IMAGE4_API_AVAILABLE_SPRING_2024 102 OS_EXPORT 103 const image4_trust_evaluation_t _image4_trust_evaluation_sign; 104 #define IMAGE4_TRUST_EVALUATION_SIGN (&_image4_trust_evaluation_sign) 105 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_sign); 106 107 /*! 108 * @const IMAGE4_TRUST_EVALUATION_BOOT 109 * The trust evaluation is intended to bootstrap a subsequent trust evaluation 110 * in a chain of trust. The ultimate purpose of the chain of trust must be to 111 * either preflight a manifest or sign it. 112 * 113 * This type of trust evaluation does not require a payload. 114 * 115 * @section Trust Evaluation Result 116 * This type of trust evaluation is not intended to be performed directly by way 117 * of {@link image4_trust_evaluate}. It is instead intended to create a trust 118 * object which can be used as a previous stage of boot for another trust object 119 * by way of {@link image4_trust_set_booter}. 120 * 121 * However, if the caller wishes to perform a boot trust evaluation directly, 122 * then the trust evaluation result equivalent to that of 123 * {@link IMAGE4_TRUST_EVALUATION_SIGN}. 124 * 125 * @discussion 126 * This trust evaluation is supported on all targets. 127 */ 128 IMAGE4_API_AVAILABLE_SPRING_2024 129 OS_EXPORT 130 const image4_trust_evaluation_t _image4_trust_evaluation_boot; 131 #define IMAGE4_TRUST_EVALUATION_BOOT (&_image4_trust_evaluation_boot) 132 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_boot); 133 134 /*! 135 * @const IMAGE4_TRUST_EVALUATION_NORMALIZE 136 * The trust evaluation is intended to produce a normalized form of an Image4 137 * manifest known as a "policy closure". This form of a manifest describes all 138 * possible personalized instantiations of a manifest. The normalized contents 139 * include all items in the signed section, i.e. all object dictionaries are 140 * captured. 141 * 142 * Because this type of trust evaluation operates on all objects in the 143 * manifest (as opposed to the object corresponding to a specific payload), only 144 * manifest properties are recorded through the 145 * {@link image4_trust_record_property_*} family of APIs. The property values 146 * recorded are the ones from the source manifest, not the ones which were 147 * inserted into the policy closure. 148 * 149 * Any payload provided to this type of trust evaluation is ignored. 150 * 151 * @section Trust Evaluation Result 152 * Upon successful evaluation, the result is a pointer to the resulting Image4 153 * manifest object representing the closure. 154 * 155 * @discussion 156 * This trust evaluation is only supported on targets which have an allocator. 157 * The pointer to the resulting bytes is not valid beyond the scope of the 158 * trust evaluation callback. 159 * 160 * @availability 161 * This constant first became available in API version 20231215. 162 */ 163 IMAGE4_API_AVAILABLE_FALL_2024 164 OS_EXPORT 165 const image4_trust_evaluation_t _image4_trust_evaluation_normalize; 166 #define IMAGE4_TRUST_EVALUATION_NORMALIZE (&_image4_trust_evaluation_normalize) 167 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_normalize); 168 169 OS_ASSUME_PTR_ABI_SINGLE_END 170 OS_ASSUME_NONNULL_END 171 __END_DECLS 172 173 #endif // __IMAGE4_API_TRUST_EVALUATION_H 174