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
60OS_ASSUME_NONNULL_BEGIN
61OS_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 */
112typedef 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 */
137OS_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 */
170typedef 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
203image4_cs_trap_argv_decl(kmod_set_release_type) {
204 char __cs_copy csmx_release_type[64];
205};
206
207image4_cs_trap_argv_decl(kmod_set_boot_uuid) {
208 uint8_t __cs_copy csmx_uuid[16];
209};
210
211
212
213image4_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
220image4_cs_trap_argv_decl(nonce_roll) {
221 uint64_t csmx_handle;
222};
223
224image4_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 */
244OS_EXPORT OS_WARN_RESULT
245image4_cs_trap_handler_t _Nullable
246image4_cs_trap_resolve_handler(image4_cs_trap_t trap);
247IMAGE4_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 */
260OS_EXPORT OS_WARN_RESULT
261ssize_t
262image4_cs_trap_vector_size(image4_cs_trap_t trap);
263IMAGE4_XNU_AVAILABLE_DIRECT(image4_cs_trap_vector_size);
264
265OS_ASSUME_PTR_ABI_SINGLE_END
266OS_ASSUME_NONNULL_END
267__END_DECLS
268
269#endif // __IMAGE4_CS_TRAPS_H
270