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 * Supported coprocessors. 31 */ 32 #ifndef __IMAGE4_API_COPROCESSOR_H 33 #define __IMAGE4_API_COPROCESSOR_H 34 35 #include <image4/image4.h> 36 #include <image4/types.h> 37 38 /*! 39 * @section TAPI 40 * TAPI doesn't like this because it sort of functions as an umbrella header 41 * rather than each of these sub-headers being self-contained. But we don't want 42 * to specify this as the public umbrella header because it isn't. We just do 43 * this because these coprocessor definitions used to all be in this header, but 44 * then it started getting crowded, so we broke them out and didn't want to 45 * break dependent projects, which made TAPI upset. 46 * 47 * So we just don't tell it about the umbrella nature here, since these headers 48 * are all self-contained; it's just that we have to make their content 49 * available through just an inclusion of this header. 50 */ 51 #if !IMAGE4_INSTALLAPI 52 #include <image4/coprocessor/ap.h> 53 #include <image4/coprocessor/ap_local.h> 54 #include <image4/coprocessor/bootpc.h> 55 #include <image4/coprocessor/cryptex1.h> 56 #include <image4/coprocessor/sep.h> 57 #include <image4/coprocessor/vma2.h> 58 #include <image4/coprocessor/vma3.h> 59 #include <image4/coprocessor/x86.h> 60 #endif 61 62 __BEGIN_DECLS 63 OS_ASSUME_NONNULL_BEGIN 64 OS_ASSUME_PTR_ABI_SINGLE_BEGIN 65 66 #pragma mark Definitions 67 /*! 68 * @const IMAGE4_COPROCESSOR_ARRAY_CNT 69 * The maximum number of coprocessors that can be represented in an array given 70 * to {@link image4_coprocessor_resolve_from_manifest}. 71 */ 72 #define IMAGE4_COPROCESSOR_ARRAY_CNT (3u) 73 74 #pragma mark Host Coprocessor 75 /*! 76 * @const IMAGE4_COPROCESSOR_HOST 77 * The host execution environment. This environment does not support handles. 78 */ 79 IMAGE4_API_AVAILABLE_SPRING_2024 80 OS_EXPORT 81 const image4_coprocessor_t _image4_coprocessor_host; 82 #define IMAGE4_COPROCESSOR_HOST (&_image4_coprocessor_host) 83 IMAGE4_XNU_AVAILABLE_INDIRECT(_image4_coprocessor_host); 84 85 /*! 86 * @const IMAGE4_COPROCESSOR_HANDLE_HOST_DEFAULT 87 * The default handle for {@link IMAGE4_COPROCESSOR_HOST}. This constant enables 88 * `DEFAULT` to be used as the second and third arguments to 89 * {@link image4_environment_init_coproc} and 90 * {@link image4_environment_new_coproc} respectively. 91 */ 92 #define IMAGE4_COPROCESSOR_HANDLE_HOST_DEFAULT 0 93 94 #pragma mark API 95 /*! 96 * @function image4_coprocessor_resolve_from_manifest 97 * Resolves the coprocessor environment associated with a manifest. 98 * 99 * @param manifest 100 * A pointer to the Image4 manifest bytes. This buffer may refer to a stitched 101 * manifest and payload object, in which case the implementation will extract 102 * the manifest portion. 103 * 104 * @param manifest_len 105 * The length of the buffer referenced by {@link manifest}. 106 * 107 * @param coprocs 108 * The list of coprocessors which could possibly authenticate the manifest. This 109 * list should be kept as small as possible. 110 * 111 * @result 112 * The coprocessor environment that can be used to authenticate the manifest, or 113 * NULL if none of the provided coprocessors could be used. 114 * 115 * @discussion 116 * Generally speaking, callers should have a priori, static knowledge of the 117 * environment in which they authenticate payloads. If the caller is responsible 118 * for handling payloads for multiple coprocessors, it should make the decision 119 * of which coprocessor to use based on static environmental properties or 120 * properties that have been forwarded from the previous stage of boot. 121 * 122 * This interface's existence is a conceit that this is not always possible for 123 * certain trust evaluations, e.g. evaluations that need to evaluate content 124 * provided by another execution context in order to counter-sign it. In such 125 * cases, multiple different manifests for multiple different coprocessor 126 * environments may need to be evaluated. 127 * 128 * This interface intentionally does not attempt to resolve a coprocessor 129 * handle. The caller must still possess static knowledge of which handle must 130 * be used for which coprocessor. 131 * 132 * @availability 133 * This function first became available in API version 20240216. 134 */ 135 IMAGE4_API_AVAILABLE_FALL_2024 136 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3 137 const image4_coprocessor_t *_Nullable 138 image4_coprocessor_resolve_from_manifest( 139 const void *__sized_by(manifest_len) manifest, 140 size_t manifest_len, 141 const image4_coprocessor_t *_Nullable coprocs[ 142 _Nonnull __static_size IMAGE4_COPROCESSOR_ARRAY_CNT]); 143 IMAGE4_XNU_AVAILABLE_DIRECT(image4_coprocessor_resolve_from_manifest); 144 145 OS_ASSUME_PTR_ABI_SINGLE_END 146 OS_ASSUME_NONNULL_END 147 __END_DECLS 148 149 #endif // __IMAGE4_API_COPROCESSOR_H 150