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
40#ifdef XNU_PLATFORM_BridgeOS
41#define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 1
42#elif defined(TARGET_OS_BRIDGE) && TARGET_OS_BRIDGE
43#define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 1
44#else
45#define XNU_HAS_LEGACY_TRUST_CACHE_LOADING 0
46#endif
47
48__BEGIN_DECLS
49
50#if XNU_KERNEL_PRIVATE
51
52/* Temporary definition until we get a proper shared one */
53typedef struct DTTrustCacheRange {
54 vm_offset_t paddr;
55 size_t length;
56} DTTrustCacheRange;
57
58/* This is the structure iBoot uses to deliver the trust caches to the system */
59typedef struct _trust_cache_offsets {
60 /* The number of trust caches provided */
61 uint32_t num_caches;
62
63 /* Offset of each from beginning of the structure */
64 uint32_t offsets[0];
65} __attribute__((__packed__)) trust_cache_offsets_t;
66
67/**
68 * Initialize the trust cache runtime for the system environment.
69 */
70void
71trust_cache_runtime_init(void);
72
73/**
74 * Load the static and engineering trust caches passed over to the system by the boot loader.
75 */
76void
77load_static_trust_cache(void);
78
79#endif /* XNU_KERNEL_PRIVATE */
80
81/**
82 * Check the capabilities of the static trust caches on the system. Since the static trust
83 * caches are loaded at boot, kernel extensions don't get a chance to observe their format
84 * and miss out on the information.
85 *
86 * This function can be queried to obtain this information.
87 */
88kern_return_t
89static_trust_cache_capabilities(
90 uint32_t *num_static_trust_caches_ret,
91 TCCapabilities_t *capabilities0_ret,
92 TCCapabilities_t *capabilities1_ret);
93
94/**
95 * Check if a particular trust cache has already been loaded into the system on the basis
96 * of a provided UUID.
97 *
98 * Based on the system environment, this request may trap into the kernel's code signing
99 * monitor environment as the trust cache data structures need to be locked down.
100 */
101kern_return_t
102check_trust_cache_runtime_for_uuid(
103 const uint8_t check_uuid[kUUIDSize]);
104
105/**
106 * Load an image4 trust cache. Since the type of trust cache isn't specified, this interface
107 * attempts to validate the trust cache through all known types. Therefore, this evaluation
108 * can be expensive.
109 *
110 * This is a deprecated interface and should no longer be used. It also doesn't support usage
111 * of the auxiliary manifest. Please use the newer interface "load_trust_cache_with_type".
112 */
113kern_return_t
114load_trust_cache(
115 const uint8_t *img4_object, const size_t img4_object_len,
116 const uint8_t *img4_ext_manifest, const size_t img4_ext_manifest_len);
117
118/**
119 * Load an image4 based trust cache of a particular type. This function performs an entitlement
120 * check on the calling process to ensure it has the entitlement for loading the specified trust
121 * cache.
122 *
123 * Based on the system environment, the trust cache may be loaded into kernel memory, or it may
124 * be loaded into memory controlled by the kernel monitor environment. In either case, this
125 * function creates its own allocations for the data, and the caller may free their allocations,
126 * if any.
127 */
128kern_return_t
129load_trust_cache_with_type(
130 TCType_t type,
131 const uint8_t *img4_object, const size_t img4_object_len,
132 const uint8_t *img4_ext_manifest, const size_t img4_ext_manifest_len,
133 const uint8_t *img4_aux_manifest, const size_t img4_aux_manifest_len);
134
135/**
136 * Load a legacy trust cache module for supported platforms. Availability for the KPI can
137 * be checked by querying the macro "XNU_HAS_LEGACY_TRUST_CACHE_LOADING". Using this KPI
138 * on an unsupported platform will panic the system.
139 */
140kern_return_t
141load_legacy_trust_cache(
142 const uint8_t *module_data, const size_t module_size);
143
144/**
145 * Query a trust cache based on the type passed in.
146 *
147 * Based on the system environment, the trust cache may be queried from kernel memory, or it may
148 * be queried from memory controller by the kernel monitor environment.
149 */
150kern_return_t
151query_trust_cache(
152 TCQueryType_t query_type,
153 const uint8_t cdhash[kTCEntryHashSize],
154 TrustCacheQueryToken_t *query_token);
155
156__END_DECLS
157
158#endif /* KERNEL_PRIVATE */
159#endif /* _SYS_TRUST_CACHES_H_ */
160