1 /* 2 * Copyright (c) 2022 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23 #ifndef _SYS_TRUST_CACHES_H_ 24 #define _SYS_TRUST_CACHES_H_ 25 26 #ifdef KERNEL_PRIVATE 27 28 #include <mach/kern_return.h> 29 #include <sys/cdefs.h> 30 #include <TrustCache/API.h> 31 32 #if (DEVELOPMENT || DEBUG) 33 #define TRUST_CACHE_INCLUDE_INTERNAL_CODE 1 34 #endif 35 36 /* Availability macros to check for support */ 37 #define XNU_HAS_TRUST_CACHE_LOADING 1 38 #define XNU_HAS_TRUST_CACHE_CHECK_RUNTIME_FOR_UUID 1 39 #define XNU_HAS_TRUST_CACHE_QUERY_FOR_REM 1 40 #define XNU_HAS_TRUST_CACHE_UNLOADING 1 41 42 #ifdef XNU_PLATFORM_BridgeOS 43 #define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 1 44 #elif defined(TARGET_OS_BRIDGE) && TARGET_OS_BRIDGE 45 #define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 1 46 #else 47 #define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 0 48 #endif 49 50 __BEGIN_DECLS 51 52 #if XNU_KERNEL_PRIVATE 53 54 /* Common variables which represent the number of loaded trust caches */ 55 extern uint32_t num_static_trust_caches; 56 extern uint32_t num_engineering_trust_caches; 57 extern uint32_t num_loadable_trust_caches; 58 59 /* Temporary definition until we get a proper shared one */ 60 typedef struct DTTrustCacheRange { 61 vm_offset_t paddr; 62 size_t length; 63 } DTTrustCacheRange; 64 65 /* This is the structure iBoot uses to deliver the trust caches to the system */ 66 typedef struct _trust_cache_offsets { 67 /* The number of trust caches provided */ 68 uint32_t num_caches; 69 70 /* Offset of each from beginning of the structure */ 71 uint32_t offsets[0]; 72 } __attribute__((__packed__)) trust_cache_offsets_t; 73 74 /** 75 * Initialize the trust cache runtime for the system environment. 76 */ 77 void 78 trust_cache_runtime_init(void); 79 80 /** 81 * Load the static and engineering trust caches passed over to the system by the boot loader. 82 */ 83 void 84 load_static_trust_cache(void); 85 86 #endif /* XNU_KERNEL_PRIVATE */ 87 88 /** 89 * Check the capabilities of the static trust caches on the system. Since the static trust 90 * caches are loaded at boot, kernel extensions don't get a chance to observe their format 91 * and miss out on the information. 92 * 93 * This function can be queried to obtain this information. 94 */ 95 kern_return_t 96 static_trust_cache_capabilities( 97 uint32_t *num_static_trust_caches_ret, 98 TCCapabilities_t *capabilities0_ret, 99 TCCapabilities_t *capabilities1_ret); 100 101 /** 102 * Check if a particular trust cache has already been loaded into the system on the basis 103 * of a provided UUID. 104 * 105 * Based on the system environment, this request may trap into the kernel's code signing 106 * monitor environment as the trust cache data structures need to be locked down. 107 */ 108 kern_return_t 109 check_trust_cache_runtime_for_uuid( 110 const uint8_t check_uuid[kUUIDSize]); 111 112 /** 113 * Unload a trust cache from the system given a UUID. Depending on the implementation, this 114 * may eiher genuinely unload the trust cache from the system, or it may simply tombstone 115 * the trust cache such that it can't be used any more. 116 */ 117 kern_return_t 118 unload_trust_cache(uuid_t uuid); 119 120 /** 121 * Load an image4 trust cache. Since the type of trust cache isn't specified, this interface 122 * attempts to validate the trust cache through all known types. Therefore, this evaluation 123 * can be expensive. 124 * 125 * This is a deprecated interface and should no longer be used. It also doesn't support usage 126 * of the auxiliary manifest. Please use the newer interface "load_trust_cache_with_type". 127 */ 128 kern_return_t 129 load_trust_cache( 130 const uint8_t *img4_object, const size_t img4_object_len, 131 const uint8_t *img4_ext_manifest, const size_t img4_ext_manifest_len); 132 133 /** 134 * Load an image4 based trust cache of a particular type. This function performs an entitlement 135 * check on the calling process to ensure it has the entitlement for loading the specified trust 136 * cache. 137 * 138 * Based on the system environment, the trust cache may be loaded into kernel memory, or it may 139 * be loaded into memory controlled by the kernel monitor environment. In either case, this 140 * function creates its own allocations for the data, and the caller may free their allocations, 141 * if any. 142 */ 143 kern_return_t 144 load_trust_cache_with_type( 145 TCType_t type, 146 const uint8_t *img4_object, const size_t img4_object_len, 147 const uint8_t *img4_ext_manifest, const size_t img4_ext_manifest_len, 148 const uint8_t *img4_aux_manifest, const size_t img4_aux_manifest_len); 149 150 /** 151 * Load a legacy trust cache module for supported platforms. Availability for the KPI can 152 * be checked by querying the macro "XNU_HAS_LEGACY_TRUST_CACHE_LOADING". Using this KPI 153 * on an unsupported platform will panic the system. 154 */ 155 kern_return_t 156 load_legacy_trust_cache( 157 const uint8_t *module_data, const size_t module_size); 158 159 /** 160 * Query a trust cache based on the type passed in. 161 * 162 * Based on the system environment, the trust cache may be queried from kernel memory, or it may 163 * be queried from memory controlled by the kernel monitor environment. 164 */ 165 kern_return_t 166 query_trust_cache( 167 TCQueryType_t query_type, 168 const uint8_t cdhash[kTCEntryHashSize], 169 TrustCacheQueryToken_t *query_token); 170 171 /** 172 * Query the set of loaded trust caches to find the most relevant REM permissions for a given 173 * CDHash. 174 * 175 * Based on the system environment, the trust cache may be queried from kernel memory, or it may 176 * be queried from memory controlled by the kernel monitor environment. 177 */ 178 kern_return_t 179 query_trust_cache_for_rem( 180 const uint8_t cdhash[kTCEntryHashSize], 181 uint8_t *rem_perms); 182 183 __END_DECLS 184 185 #endif /* KERNEL_PRIVATE */ 186 #endif /* _SYS_TRUST_CACHES_H_ */ 187