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 * Structures and trap handler declarations for use in the kernel's code signing
31 * monitor. On targets which have a PPL, these mediate traps between the EL2 and
32 * GL2 experts. On targets which have a TXM, these mediate traps from EL2 to
33 * GL0, which uses libimage4_TXM and not the kernel implementation.
34 */
35 #ifndef __IMAGE4_CS_TRAPS_H
36 #define __IMAGE4_CS_TRAPS_H
37
38 #include <os/base.h>
39 #include <stdint.h>
40 #include <sys/types.h>
41 #include <image4/image4.h>
42
43 #if XNU_KERNEL_PRIVATE
44 #include <sys/_types/_ssize_t.h>
45
46 #if !defined(IMAGE4_DIAGNOSTIC_TRAP_LEVEL)
47 #if DEBUG || KASAN
48 #define IMAGE4_DIAGNOSTIC_TRAP_LEVEL 2
49 #elif DEVELOPMENT
50 #define IMAGE4_DIAGNOSTIC_TRAP_LEVEL 1
51 #elif RELEASE
52 #define IMAGE4_DIAGNOSTIC_TRAP_LEVEL 0
53 #else
54 #define IMAGE4_DIAGNOSTIC_TRAP_LEVEL 0
55 #endif
56 #endif // !defined(IMAGE4_DIAGNOSTIC_TRAP_LEVEL)
57 #endif // XNU_KERNEL_PRIVATE
58
59 __BEGIN_DECLS
60 OS_ASSUME_NONNULL_BEGIN
61 OS_ASSUME_PTR_ABI_SINGLE_BEGIN
62
63 /*!
64 * @const IMAGE4_CS_API_VERSION
65 * The version of the trap API which is supported by the current implementation.
66 * Successive versions will only introduce new traps. If a trap's ABI has to
67 * change, a new trap will be introduced, and the old one retired.
68 */
69 #define IMAGE4_CS_API_VERSION (0u)
70
71 #pragma mark Parameter Attributes
72 /*!
73 * @const __cs_copy
74 * The trap vector parameter is fixed-size and should be copied into the
75 * supervisor's address space.
76 */
77 #define __cs_copy
78
79 /*!
80 * @const __cs_xfer
81 * The trap vector parameter is a pointer with an associated length, and control
82 * of the subject memory should be transferred to the supervisor permanently.
83 */
84 #define __cs_xfer
85
86 /*!
87 * @const __cs_borrow
88 * The trap vector parameter is a pointer with an associated length, and control
89 * of the subject memory should be temporarily transferred to the supervisor,
90 * being returned at the conclusion of the trap.
91 */
92 #define __cs_borrow
93
94 /*!
95 * @const __cs_nullable
96 * The trap vector parameter is a pointer which may be NULL.
97 */
98 #define __cs_nullable
99
100 /*!
101 * @const __cs_diagnostic
102 * Indicates that the trap vector is for a trap which is only implemented in
103 * DEBUG build variants.
104 */
105 #define __cs_diagnostic
106
107 #pragma mark Types
108 /*!
109 * @typedef image4_cs_addr_t
110 * A type representing an address used in a trap argument vector.
111 */
112 typedef uintptr_t image4_cs_addr_t;
113
114 /*!
115 * @enum image4_cs_trap_t
116 * An enumeration describing all supported traps from the EL2 expert to its
117 * code signing supervisor.
118 *
119 * @const IMAGE4_CS_TRAP_KMOD_SET_RELEASE_TYPE
120 * Set the OS release type to inform the availability of the research cryptex
121 * nonce. Can only be called once.
122 *
123 * @const IMAGE4_CS_TRAP_NONCE_SET
124 * Sets the active nonce for a nonce domain. Both the cleartext nonce and its
125 * encrypted form are set.
126 *
127 * @const IMAGE4_CS_TRAP_NONCE_ROLL
128 * Marks a nonce as rolled such that it new trust evaluations using the nonce
129 * will fail. The nonce will be re-generated at the next boot.
130 *
131 * @const IMAGE4_CS_TRAP_IMAGE_ACTIVATE
132 * Activates an image in the GL2 context.
133 *
134 * @const IMAGE4_CS_TRAP_SET_BOOT_UUID
135 * Set the boot session UUID to inform nonce choices for MobileAsset.
136 */
137 OS_CLOSED_ENUM(image4_cs_trap, uint64_t,
138 IMAGE4_CS_TRAP_KMOD_SET_RELEASE_TYPE,
139 IMAGE4_CS_TRAP_RESERVED_0,
140 IMAGE4_CS_TRAP_RESERVED_1,
141 IMAGE4_CS_TRAP_NONCE_SET,
142 IMAGE4_CS_TRAP_NONCE_ROLL,
143 IMAGE4_CS_TRAP_IMAGE_ACTIVATE,
144 IMAGE4_CS_TRAP_KMOD_SET_BOOT_UUID,
145 _IMAGE4_CS_TRAP_CNT,
146 );
147
148 /*!
149 * @typedef image4_cs_trap_handler_t
150 * A handler for a GL2 or GL0 trap.
151 *
152 * @param csmx
153 * The trap code.
154 *
155 * @param argv
156 * The input argument structure.
157 *
158 * @param argv_len
159 * The length of {@link argv}.
160 *
161 * @param argv_out
162 * The output argument structure. Upon successful return, this structure will be
163 * populated. Otherwise, the implementation will not modify this memory.
164 *
165 * @param argv_out_len
166 * The length of {@link argv_out}.
167 *
168 * @result
169 * Upon success, zero is returned. Upon failure, a POSIX error code describing
170 * the failure condition.
171 */
172 typedef errno_t (*image4_cs_trap_handler_t)(
173 image4_cs_trap_t csmx,
174 const void *argv,
175 size_t argv_len,
176 void *_Nullable argv_out,
177 size_t *_Nullable argv_out_len
178 );
179
180 /*!
181 * @function image4_cs_trap_handler
182 * Macro which expands to a function name suitable for a trap handler.
183 *
184 * @param _el
185 * The execution level in which the trap resides.
186 *
187 * @param _where
188 * The subsystem of the trap.
189 *
190 * @param _which
191 * The name of the trap.
192 */
193 #define image4_cs_trap_handler(_el, _where, _which) \
194 _image4_ ## _el ## _cs_trap_ ## _where ## _ ## _which
195
196 #pragma mark Trap Arguments
197 #define image4_cs_trap_argv(_which) \
198 image4_cs_trap_argv_ ## _which ## _t
199
200 #define image4_cs_trap_argv_decl(_which) \
201 typedef struct _image4_cs_trap_argv_ ## _which \
202 image4_cs_trap_argv(_which); \
203 struct __attribute__((packed)) _image4_cs_trap_argv_ ## _which
204
image4_cs_trap_argv_decl(kmod_set_release_type)205 image4_cs_trap_argv_decl(kmod_set_release_type) {
206 char __cs_copy csmx_release_type[64];
207 };
208
image4_cs_trap_argv_decl(kmod_set_boot_uuid)209 image4_cs_trap_argv_decl(kmod_set_boot_uuid) {
210 uint8_t __cs_copy csmx_uuid[16];
211 };
212
213
214
image4_cs_trap_argv_decl(nonce_set)215 image4_cs_trap_argv_decl(nonce_set) {
216 uint64_t csmx_handle;
217 uint32_t csmx_flags;
218 uint8_t __cs_copy csmx_clear[16];
219 uint8_t __cs_copy csmx_cipher[16];
220 };
221
image4_cs_trap_argv_decl(nonce_roll)222 image4_cs_trap_argv_decl(nonce_roll) {
223 uint64_t csmx_handle;
224 };
225
image4_cs_trap_argv_decl(image_activate)226 image4_cs_trap_argv_decl(image_activate) {
227 uint64_t csmx_handle;
228 image4_cs_addr_t __cs_xfer csmx_payload;
229 uint32_t csmx_payload_len;
230 image4_cs_addr_t __cs_xfer csmx_manifest;
231 uint32_t csmx_manifest_len;
232 };
233
234 #pragma mark API
235 /*!
236 * @function image4_cs_trap_resolve_handler
237 * Resolves a trap code to a handler function.
238 *
239 * @param trap
240 * The trap code to resolve.
241 *
242 * @result
243 * A function pointer corresponding to the entry point for the given trap code.
244 * If the given trap is not implemented, NULL is returned.
245 */
246 OS_EXPORT OS_WARN_RESULT
247 image4_cs_trap_handler_t _Nullable
248 image4_cs_trap_resolve_handler(image4_cs_trap_t trap);
249 IMAGE4_XNU_AVAILABLE_DIRECT(image4_cs_trap_resolve_handler);
250
251 /*!
252 * @function image4_cs_trap_vector_size
253 * Returns the expected size of the argument vector for the provided trap.
254 *
255 * @param trap
256 * The trap code for which to obtain the size.
257 *
258 * @result
259 * The size of the argument vector in bytes of the provided trap. If the trap
260 * number is invalid or not supported by the implementation, -1 is returned.
261 */
262 OS_EXPORT OS_WARN_RESULT
263 ssize_t
264 image4_cs_trap_vector_size(image4_cs_trap_t trap);
265 IMAGE4_XNU_AVAILABLE_DIRECT(image4_cs_trap_vector_size);
266
267 OS_ASSUME_PTR_ABI_SINGLE_END
268 OS_ASSUME_NONNULL_END
269 __END_DECLS
270
271 #endif // __IMAGE4_CS_TRAPS_H
272