1/*
2 * Copyright (c) 2019 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#ifndef _REASON_H_
30#define _REASON_H_
31
32#include <stdint.h>
33
34__BEGIN_DECLS
35
36#ifdef KERNEL_PRIVATE
37
38#include <kern/kern_cdata.h>
39
40#ifdef XNU_KERNEL_PRIVATE
41#include <os/refcnt.h>
42#include <kern/locks.h>
43
44typedef struct os_reason {
45 decl_lck_mtx_data(, osr_lock);
46 os_refcnt_t osr_refcount;
47 uint32_t osr_namespace;
48 uint64_t osr_code;
49 uint64_t osr_flags;
50 uint32_t osr_bufsize;
51 struct kcdata_descriptor osr_kcd_descriptor;
52 char *osr_kcd_buf;
53} *os_reason_t;
54
55#define OS_REASON_NULL ((os_reason_t) NULL)
56
57/* We only include 800 bytes of the exit reason description to not blow through the panic buffer */
58#define LAUNCHD_PANIC_REASON_STRING_MAXLEN "800"
59
60void os_reason_init(void);
61
62os_reason_t build_userspace_exit_reason(uint32_t reason_namespace, uint64_t reason_code, user_addr_t payload, uint32_t payload_size,
63 user_addr_t reason_string, uint64_t reason_flags);
64char *exit_reason_get_string_desc(os_reason_t exit_reason);
65
66/* The blocking allocation is currently not exported to KEXTs */
67int os_reason_alloc_buffer(os_reason_t cur_reason, uint32_t osr_bufsize);
68
69#else /* XNU_KERNEL_PRIVATE */
70
71typedef void * os_reason_t;
72
73#endif /* XNU_KERNEL_PRIVATE */
74
75os_reason_t os_reason_create(uint32_t osr_namespace, uint64_t osr_code);
76int os_reason_alloc_buffer_noblock(os_reason_t cur_reason, uint32_t osr_bufsize);
77struct kcdata_descriptor * os_reason_get_kcdata_descriptor(os_reason_t cur_reason);
78void os_reason_ref(os_reason_t cur_reason);
79void os_reason_free(os_reason_t cur_reason);
80void os_reason_set_flags(os_reason_t cur_reason, uint64_t flags);
81void os_reason_set_description_data(os_reason_t cur_reason, uint32_t type, void *reason_data, uint32_t reason_data_len);
82#endif /* KERNEL_PRIVATE */
83
84/*
85 * Reason namespaces.
86 */
87#define OS_REASON_INVALID 0
88#define OS_REASON_JETSAM 1
89#define OS_REASON_SIGNAL 2
90#define OS_REASON_CODESIGNING 3
91#define OS_REASON_HANGTRACER 4
92#define OS_REASON_TEST 5
93#define OS_REASON_DYLD 6
94#define OS_REASON_LIBXPC 7
95#define OS_REASON_OBJC 8
96#define OS_REASON_EXEC 9
97#define OS_REASON_SPRINGBOARD 10
98#define OS_REASON_TCC 11
99#define OS_REASON_REPORTCRASH 12
100#define OS_REASON_COREANIMATION 13
101#define OS_REASON_AGGREGATED 14
102#define OS_REASON_RUNNINGBOARD 15
103#define OS_REASON_ASSERTIOND OS_REASON_RUNNINGBOARD /* old name */
104#define OS_REASON_SKYWALK 16
105#define OS_REASON_SETTINGS 17
106#define OS_REASON_LIBSYSTEM 18
107#define OS_REASON_FOUNDATION 19
108#define OS_REASON_WATCHDOG 20
109#define OS_REASON_METAL 21
110#define OS_REASON_WATCHKIT 22
111#define OS_REASON_GUARD 23
112#define OS_REASON_ANALYTICS 24
113#define OS_REASON_SANDBOX 25
114#define OS_REASON_SECURITY 26
115#define OS_REASON_ENDPOINTSECURITY 27
116#define OS_REASON_PAC_EXCEPTION 28
117#define OS_REASON_BLUETOOTH_CHIP 29
118#define OS_REASON_PORT_SPACE 30
119#define OS_REASON_WEBKIT 31
120#define OS_REASON_BACKLIGHTSERVICES 32
121#define OS_REASON_MEDIA 33
122#define OS_REASON_ROSETTA 34
123#define OS_REASON_LIBIGNITION 35
124#define OS_REASON_BOOTMOUNT 36
125
126
127#define OS_REASON_REALITYKIT 38
128
129/*
130 * Update whenever new OS_REASON namespaces are added.
131 */
132#define OS_REASON_MAX_VALID_NAMESPACE OS_REASON_REALITYKIT
133
134#define OS_REASON_BUFFER_MAX_SIZE 5120
135
136#define OS_REASON_FLAG_NO_CRASH_REPORT 0x1 /* Don't create a crash report */
137#define OS_REASON_FLAG_GENERATE_CRASH_REPORT 0x2 /* Create a crash report - the default for userspace requests */
138#define OS_REASON_FLAG_FROM_USERSPACE 0x4 /* Reason created from a userspace syscall */
139#define OS_REASON_FLAG_FAILED_DATA_COPYIN 0x8 /* We failed to copyin data from userspace */
140#define OS_REASON_FLAG_PAYLOAD_TRUNCATED 0x10 /* The payload was truncated because it was longer than allowed */
141#define OS_REASON_FLAG_BAD_PARAMS 0x20 /* Invalid parameters were passed involved with creating this reason */
142#define OS_REASON_FLAG_CONSISTENT_FAILURE 0x40 /* Whatever caused this reason to be created will happen again */
143#define OS_REASON_FLAG_ONE_TIME_FAILURE 0x80 /* Whatever caused this reason to be created was a one time issue */
144#define OS_REASON_FLAG_NO_CRASHED_TID 0x100 /* Don't include the TID that processed the exit in the crash report */
145#define OS_REASON_FLAG_ABORT 0x200 /* Reason created from abort_* rather than terminate_* */
146#define OS_REASON_FLAG_SHAREDREGION_FAULT 0x400 /* Fault happened within the shared cache region */
147#define OS_REASON_FLAG_CAPTURE_LOGS 0x800 /* The report generated for this reason should capture logs */
148#define OS_REASON_FLAG_SECURITY_SENSITIVE 0x1000 /* Mark as security sensitive for priority treatment */
149
150/*
151 * Set of flags that are allowed to be passed from userspace
152 */
153#define OS_REASON_FLAG_MASK_ALLOWED_FROM_USER (OS_REASON_FLAG_CONSISTENT_FAILURE | OS_REASON_FLAG_ONE_TIME_FAILURE | OS_REASON_FLAG_NO_CRASH_REPORT | OS_REASON_FLAG_ABORT | OS_REASON_FLAG_CAPTURE_LOGS | OS_REASON_FLAG_SECURITY_SENSITIVE)
154
155/*
156 * Macros to encode the exit reason namespace and first 32 bits of code in exception code
157 * which is used by Report Crash as a hint. It should be only used as a hint since it
158 * loses higher 32 bits of exit reason code.
159 */
160#define ENCODE_OSR_NAMESPACE_TO_MACH_EXCEPTION_CODE(code, osr_namespace) \
161 (code) = (code) | (((osr_namespace) & ((uint64_t)UINT32_MAX)) << 32)
162#define ENCODE_OSR_CODE_TO_MACH_EXCEPTION_CODE(code, osr_code) \
163 (code) = (code) | ((osr_code) & ((uint64_t)UINT32_MAX))
164
165#ifndef KERNEL
166/*
167 * abort_with_reason: Used to exit the current process and pass along
168 * specific information about why it is being terminated.
169 *
170 * Inputs: args->reason_namespace - OS_REASON namespace specified for the reason
171 * args->reason_code - code in the specified namespace for the reason
172 * args->reason_string - additional string formatted information about the request
173 * args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above).
174 *
175 * Outputs: Does not return.
176 */
177void abort_with_reason(uint32_t reason_namespace, uint64_t reason_code, const char *reason_string, uint64_t reason_flags)
178__attribute__((noreturn, cold));
179
180/*
181 * abort_with_payload: Used to exit the current process and pass along
182 * specific information about why it is being terminated. The payload pointer
183 * should point to structured data that can be interpreted by the consumer of
184 * exit reason information.
185 *
186 * Inputs: args->reason_namespace - OS_REASON namespace specified for the reason
187 * args->reason_code - code in the specified namespace for the reason
188 * args->payload - pointer to payload structure in user space
189 * args->payload_size - length of payload buffer (this will be truncated to EXIT_REASON_PAYLOAD_MAX_LEN)
190 * args->reason_string - additional string formatted information about the request
191 * args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above).
192 *
193 * Outputs: Does not return.
194 */
195void abort_with_payload(uint32_t reason_namespace, uint64_t reason_code, void *payload, uint32_t payload_size, const char *reason_string,
196 uint64_t reason_flags) __attribute__((noreturn, cold));
197
198/*
199 * terminate_with_reason: Used to terminate a specific process and pass along
200 * specific information about why it is being terminated.
201 *
202 * Inputs: args->pid - the PID of the process to be terminated
203 * args->reason_namespace - OS_REASON namespace specified for the reason
204 * args->reason_code - code in the specified namespace for the reason
205 * args->reason_string - additional string formatted information about the request
206 * args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above)
207 *
208 * Outputs: returns -1 and sets errno to EINVAL if the PID requested is the same as that of the calling process, invalid or the namespace provided is invalid.
209 * returns -1 and sets errno to ESRCH if we couldn't find a live process with the requested PID
210 * returns -1 and sets errno to EPERM if the caller is not privileged enough to kill the process with the requested PID
211 * returns 0 otherwise
212 */
213int terminate_with_reason(int pid, uint32_t reason_namespace, uint64_t reason_code, const char *reason_string, uint64_t reason_flags);
214
215/*
216 * terminate_with_payload: Used to terminate a specific process and pass along
217 * specific information about why it is being terminated. The payload pointer
218 * should point to structured data that can be interpreted by the consumer of
219 * exit reason information.
220 *
221 * Inputs: args->pid - the PID of the process to be terminated.
222 * args->reason_namespace - OS_REASON namespace specified for the reason
223 * args->reason_code - code in the specified namespace for the reason
224 * args->payload - pointer to payload structure in user space
225 * args->payload_size - length of payload buffer (this will be truncated to EXIT_REASON_PAYLOAD_MAX_LEN)
226 * args->reason_string - additional string formatted information about the request
227 * args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above)
228 *
229 * Outputs: returns -1 and sets errno to EINVAL if the PID requested is the same as that of the calling process, is invalid or the namespace provided is invalid.
230 * returns -1 and sets errno to ESRCH if we couldn't find a live process with the requested PID
231 * returns -1 and sets errno to EPERM if the caller is not privileged enough to kill the process with the requested PID
232 * returns 0 otherwise
233 */
234int terminate_with_payload(int pid, uint32_t reason_namespace, uint64_t reason_code, void *payload, uint32_t payload_size,
235 const char *reason_string, uint64_t reason_flags);
236#endif /* KERNEL */
237
238/*
239 * codesigning exit reasons
240 */
241#define CODESIGNING_EXIT_REASON_TASKGATED_INVALID_SIG 1
242#define CODESIGNING_EXIT_REASON_INVALID_PAGE 2
243#define CODESIGNING_EXIT_REASON_TASK_ACCESS_PORT 3
244#define CODESIGNING_EXIT_REASON_LAUNCH_CONSTRAINT_VIOLATION 4
245/*
246 * exec path specific exit reasons
247 */
248#define EXEC_EXIT_REASON_BAD_MACHO 1
249#define EXEC_EXIT_REASON_SUGID_FAILURE 2
250#define EXEC_EXIT_REASON_ACTV_THREADSTATE 3
251#define EXEC_EXIT_REASON_STACK_ALLOC 4
252#define EXEC_EXIT_REASON_APPLE_STRING_INIT 5
253#define EXEC_EXIT_REASON_COPYOUT_STRINGS 6
254#define EXEC_EXIT_REASON_COPYOUT_DYNLINKER 7
255#define EXEC_EXIT_REASON_SECURITY_POLICY 8
256#define EXEC_EXIT_REASON_TASKGATED_OTHER 9
257#define EXEC_EXIT_REASON_FAIRPLAY_DECRYPT 10
258#define EXEC_EXIT_REASON_DECRYPT 11
259#define EXEC_EXIT_REASON_UPX 12
260#define EXEC_EXIT_REASON_NO32EXEC 13
261#define EXEC_EXIT_REASON_WRONG_PLATFORM 14
262#define EXEC_EXIT_REASON_MAIN_FD_ALLOC 15
263#define EXEC_EXIT_REASON_COPYOUT_ROSETTA 16
264#define EXEC_EXIT_REASON_SET_DYLD_INFO 17
265#define EXEC_EXIT_REASON_MACHINE_THREAD 18
266#define EXEC_EXIT_REASON_BAD_PSATTR 19
267/*
268 * guard reasons
269 */
270#define GUARD_REASON_VNODE 1
271#define GUARD_REASON_VIRT_MEMORY 2
272#define GUARD_REASON_MACH_PORT 3
273#define GUARD_REASON_EXCLAVES 4
274#define GUARD_REASON_JIT 5
275
276__END_DECLS
277
278#endif /* _REASON_H_ */
279