/* * Copyright © 2017-2024 Apple Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ /*! * @header * Encapsulation which describes an Image4 trust evaluation procedure. The type * of procedure impacts the result delivered to the * {@link image4_trust_evaluation_result_t}. * * All trust evaluations require a manifest to be present in the trust object. */ #ifndef __IMAGE4_API_TRUST_EVALUATION_H #define __IMAGE4_API_TRUST_EVALUATION_H #include #include __BEGIN_DECLS OS_ASSUME_NONNULL_BEGIN OS_ASSUME_PTR_ABI_SINGLE_BEGIN /*! * @const IMAGE4_TRUST_EVALUATION_EXEC * The trust evaluation is intended to execute firmware in the designated * environment. This is to be used for either first- or second-stage boots. * * This type of trust evaluation requires a payload. * * @section Trust Evaluation Result * Upon successful evaluation, the result is a pointer to the unwrapped Image4 * payload bytes. * * @discussion * This trust evaluation is supported on all targets. */ IMAGE4_API_AVAILABLE_SPRING_2024 OS_EXPORT const image4_trust_evaluation_t _image4_trust_evaluation_exec; #define IMAGE4_TRUST_EVALUATION_EXEC (&_image4_trust_evaluation_exec) IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_exec); /*! * @const IMAGE4_TRUST_EVALUATION_PREFLIGHT * The trust evaluation is intended to preflight a manifest to verify that it is * likely to be accepted during a boot trust evaluation in the future. This is * a best effort evaluation, and depending on the environment, certain * enforcement policies may be relaxed due to the relevant information not being * available. * * This type of trust evaluation does not require a payload. * * @section Trust Evaluation Result * The result is an error code indicating whether the manifest is likely to be * accepted by the environment. * * @discussion * This type of trust evaluation is not supported on all targets. */ IMAGE4_API_AVAILABLE_SPRING_2024 OS_EXPORT const image4_trust_evaluation_t _image4_trust_evaluation_preflight; #define IMAGE4_TRUST_EVALUATION_PREFLIGHT (&_image4_trust_evaluation_preflight) IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_preflight); /*! * @const IMAGE4_TRUST_EVALUATION_SIGN * The trust evaluation is intended to facilitate counter-signing the manifest. * * @section Trust Evaluation Result * Upon successful evaluation, the result is a pointer to the digest of the * manifest. The digest is computed using the algorithm specified by the * environment. * * @discussion * This type of trust evaluation is not supported on all targets. */ IMAGE4_API_AVAILABLE_SPRING_2024 OS_EXPORT const image4_trust_evaluation_t _image4_trust_evaluation_sign; #define IMAGE4_TRUST_EVALUATION_SIGN (&_image4_trust_evaluation_sign) IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_sign); /*! * @const IMAGE4_TRUST_EVALUATION_BOOT * The trust evaluation is intended to bootstrap a subsequent trust evaluation * in a chain of trust. The ultimate purpose of the chain of trust must be to * either preflight a manifest or sign it. * * This type of trust evaluation does not require a payload. * * @section Trust Evaluation Result * This type of trust evaluation is not intended to be performed directly by way * of {@link image4_trust_evaluate}. It is instead intended to create a trust * object which can be used as a previous stage of boot for another trust object * by way of {@link image4_trust_set_booter}. * * However, if the caller wishes to perform a boot trust evaluation directly, * then the trust evaluation result equivalent to that of * {@link IMAGE4_TRUST_EVALUATION_SIGN}. * * @discussion * This trust evaluation is supported on all targets. */ IMAGE4_API_AVAILABLE_SPRING_2024 OS_EXPORT const image4_trust_evaluation_t _image4_trust_evaluation_boot; #define IMAGE4_TRUST_EVALUATION_BOOT (&_image4_trust_evaluation_boot) IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_boot); /*! * @const IMAGE4_TRUST_EVALUATION_NORMALIZE * The trust evaluation is intended to produce a normalized form of an Image4 * manifest known as a "policy closure". This form of a manifest describes all * possible personalized instantiations of a manifest. The normalized contents * include all items in the signed section, i.e. all object dictionaries are * captured. * * Because this type of trust evaluation operates on all objects in the * manifest (as opposed to the object corresponding to a specific payload), only * manifest properties are recorded through the * {@link image4_trust_record_property_*} family of APIs. The property values * recorded are the ones from the source manifest, not the ones which were * inserted into the policy closure. * * Any payload provided to this type of trust evaluation is ignored. * * @section Trust Evaluation Result * Upon successful evaluation, the result is a pointer to the resulting Image4 * manifest object representing the closure. * * @discussion * This trust evaluation is only supported on targets which have an allocator. * The pointer to the resulting bytes is not valid beyond the scope of the * trust evaluation callback. * * @availability * This constant first became available in API version 20231215. */ IMAGE4_API_AVAILABLE_FALL_2024 OS_EXPORT const image4_trust_evaluation_t _image4_trust_evaluation_normalize; #define IMAGE4_TRUST_EVALUATION_NORMALIZE (&_image4_trust_evaluation_normalize) IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_trust_evaluation_normalize); OS_ASSUME_PTR_ABI_SINGLE_END OS_ASSUME_NONNULL_END __END_DECLS #endif // __IMAGE4_API_TRUST_EVALUATION_H