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_NONCE_SET, |
140 | IMAGE4_CS_TRAP_NONCE_ROLL, |
141 | IMAGE4_CS_TRAP_IMAGE_ACTIVATE, |
142 | IMAGE4_CS_TRAP_KMOD_SET_BOOT_UUID, |
143 | _IMAGE4_CS_TRAP_CNT, |
144 | ); |
145 | |
146 | /*! |
147 | * @typedef image4_cs_trap_handler_t |
148 | * A handler for a GL2 or GL0 trap. |
149 | * |
150 | * @param csmx |
151 | * The trap code. |
152 | * |
153 | * @param argv |
154 | * The input argument structure. |
155 | * |
156 | * @param argv_len |
157 | * The length of {@link argv}. |
158 | * |
159 | * @param argv_out |
160 | * The output argument structure. Upon successful return, this structure will be |
161 | * populated. Otherwise, the implementation will not modify this memory. |
162 | * |
163 | * @param argv_out_len |
164 | * The length of {@link argv_out}. |
165 | * |
166 | * @result |
167 | * Upon success, zero is returned. Upon failure, a POSIX error code describing |
168 | * the failure condition. |
169 | */ |
170 | typedef errno_t (*image4_cs_trap_handler_t)( |
171 | image4_cs_trap_t csmx, |
172 | const void *argv, |
173 | size_t argv_len, |
174 | void *_Nullable argv_out, |
175 | size_t *_Nullable argv_out_len |
176 | ); |
177 | |
178 | /*! |
179 | * @function image4_cs_trap_handler |
180 | * Macro which expands to a function name suitable for a trap handler. |
181 | * |
182 | * @param _el |
183 | * The execution level in which the trap resides. |
184 | * |
185 | * @param _where |
186 | * The subsystem of the trap. |
187 | * |
188 | * @param _which |
189 | * The name of the trap. |
190 | */ |
191 | #define image4_cs_trap_handler(_el, _where, _which) \ |
192 | _image4_ ## _el ## _cs_trap_ ## _where ## _ ## _which |
193 | |
194 | #pragma mark Trap Arguments |
195 | #define image4_cs_trap_argv(_which) \ |
196 | image4_cs_trap_argv_ ## _which ## _t |
197 | |
198 | #define image4_cs_trap_argv_decl(_which) \ |
199 | typedef struct _image4_cs_trap_argv_ ## _which \ |
200 | image4_cs_trap_argv(_which); \ |
201 | struct __attribute__((packed)) _image4_cs_trap_argv_ ## _which |
202 | |
203 | image4_cs_trap_argv_decl(kmod_set_release_type) { |
204 | char __cs_copy csmx_release_type[64]; |
205 | }; |
206 | |
207 | image4_cs_trap_argv_decl(kmod_set_boot_uuid) { |
208 | uint8_t __cs_copy csmx_uuid[16]; |
209 | }; |
210 | |
211 | |
212 | |
213 | image4_cs_trap_argv_decl(nonce_set) { |
214 | uint64_t csmx_handle; |
215 | uint32_t csmx_flags; |
216 | uint8_t __cs_copy csmx_clear[16]; |
217 | uint8_t __cs_copy csmx_cipher[16]; |
218 | }; |
219 | |
220 | image4_cs_trap_argv_decl(nonce_roll) { |
221 | uint64_t csmx_handle; |
222 | }; |
223 | |
224 | image4_cs_trap_argv_decl(image_activate) { |
225 | uint64_t csmx_handle; |
226 | image4_cs_addr_t __cs_xfer csmx_payload; |
227 | uint32_t csmx_payload_len; |
228 | image4_cs_addr_t __cs_xfer csmx_manifest; |
229 | uint32_t csmx_manifest_len; |
230 | }; |
231 | |
232 | #pragma mark API |
233 | /*! |
234 | * @function image4_cs_trap_resolve_handler |
235 | * Resolves a trap code to a handler function. |
236 | * |
237 | * @param trap |
238 | * The trap code to resolve. |
239 | * |
240 | * @result |
241 | * A function pointer corresponding to the entry point for the given trap code. |
242 | * If the given trap is not implemented, NULL is returned. |
243 | */ |
244 | OS_EXPORT OS_WARN_RESULT |
245 | image4_cs_trap_handler_t _Nullable |
246 | image4_cs_trap_resolve_handler(image4_cs_trap_t trap); |
247 | IMAGE4_XNU_AVAILABLE_DIRECT(image4_cs_trap_resolve_handler); |
248 | |
249 | /*! |
250 | * @function image4_cs_trap_vector_size |
251 | * Returns the expected size of the argument vector for the provided trap. |
252 | * |
253 | * @param trap |
254 | * The trap code for which to obtain the size. |
255 | * |
256 | * @result |
257 | * The size of the argument vector in bytes of the provided trap. If the trap |
258 | * number is invalid or not supported by the implementation, -1 is returned. |
259 | */ |
260 | OS_EXPORT OS_WARN_RESULT |
261 | ssize_t |
262 | image4_cs_trap_vector_size(image4_cs_trap_t trap); |
263 | IMAGE4_XNU_AVAILABLE_DIRECT(image4_cs_trap_vector_size); |
264 | |
265 | OS_ASSUME_PTR_ABI_SINGLE_END |
266 | OS_ASSUME_NONNULL_END |
267 | __END_DECLS |
268 | |
269 | #endif // __IMAGE4_CS_TRAPS_H |
270 | |