bsd/sys/reason.h

   1 /*
   2  * Copyright (c) 2016 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 <kern/locks.h>
  42
  43 typedef struct os_reason {
  44         decl_lck_mtx_data(,             osr_lock)
  45         unsigned int                    osr_refcount;
  46         uint32_t                        osr_namespace;
  47         uint64_t                        osr_code;
  48         uint64_t                        osr_flags;
  49         uint32_t                        osr_bufsize;
  50         struct kcdata_descriptor        osr_kcd_descriptor;
  51         char                            *osr_kcd_buf;
  52 } *os_reason_t;
  53
  54 #define OS_REASON_NULL ((os_reason_t) 0)
  55
  56 /* We only include 800 bytes of the exit reason description to not blow through the panic buffer */
  57 #define LAUNCHD_PANIC_REASON_STRING_MAXLEN "800"
  58
  59 void os_reason_init(void);
  60
  61 os_reason_t build_userspace_exit_reason(uint32_t reason_namespace, uint64_t reason_code, user_addr_t payload, uint32_t payload_size,
  62                                         user_addr_t reason_string, uint64_t reason_flags);
  63 char *launchd_exit_reason_get_string_desc(os_reason_t exit_reason);
  64
  65 /* The blocking allocation is currently not exported to KEXTs */
  66 int os_reason_alloc_buffer(os_reason_t cur_reason, uint32_t osr_bufsize);
  67
  68 #else /* XNU_KERNEL_PRIVATE */
  69
  70 typedef void * os_reason_t;
  71
  72 #endif /* XNU_KERNEL_PRIVATE */
  73
  74 os_reason_t os_reason_create(uint32_t osr_namespace, uint64_t osr_code);
  75 int os_reason_alloc_buffer_noblock(os_reason_t cur_reason, uint32_t osr_bufsize);
  76 struct kcdata_descriptor * os_reason_get_kcdata_descriptor(os_reason_t cur_reason);
  77 void os_reason_ref(os_reason_t cur_reason);
  78 void os_reason_free(os_reason_t cur_reason);
  79
  80 #endif /* KERNEL_PRIVATE */
  81
  82 /*
  83  * Reason namespaces.
  84  */
  85 #define OS_REASON_INVALID       0
  86 #define OS_REASON_JETSAM        1
  87 #define OS_REASON_SIGNAL        2
  88 #define OS_REASON_CODESIGNING   3
  89 #define OS_REASON_HANGTRACER    4
  90 #define OS_REASON_TEST          5
  91 #define OS_REASON_DYLD          6
  92 #define OS_REASON_LIBXPC        7
  93 #define OS_REASON_OBJC          8
  94 #define OS_REASON_EXEC          9
  95 #define OS_REASON_SPRINGBOARD   10
  96 #define OS_REASON_TCC           11
  97 #define OS_REASON_REPORTCRASH   12
  98 #define OS_REASON_COREANIMATION 13
  99 #define OS_REASON_AGGREGATED    14
 100 #define OS_REASON_ASSERTIOND    15
 101 #define OS_REASON_SKYWALK       16
 102 #define OS_REASON_SETTINGS      17
 103 #define OS_REASON_LIBSYSTEM     18
 104 #define OS_REASON_FOUNDATION    19
 105 #define OS_REASON_WATCHDOG      20
 106 #define OS_REASON_METAL         21
 107 #define OS_REASON_WATCHKIT      22
 108
 109 /*
 110  * Update whenever new OS_REASON namespaces are added.
 111  */
 112 #define OS_REASON_MAX_VALID_NAMESPACE OS_REASON_WATCHKIT
 113
 114 #define OS_REASON_BUFFER_MAX_SIZE 5120
 115
 116 #define OS_REASON_FLAG_NO_CRASH_REPORT          0x1   /* Don't create a crash report */
 117 #define OS_REASON_FLAG_GENERATE_CRASH_REPORT    0x2   /* Create a crash report - the default for userspace requests */
 118 #define OS_REASON_FLAG_FROM_USERSPACE           0x4   /* Reason created from a userspace syscall */
 119 #define OS_REASON_FLAG_FAILED_DATA_COPYIN       0x8   /* We failed to copyin data from userspace */
 120 #define OS_REASON_FLAG_PAYLOAD_TRUNCATED        0x10  /* The payload was truncated because it was longer than allowed */
 121 #define OS_REASON_FLAG_BAD_PARAMS               0x20  /* Invalid parameters were passed involved with creating this reason */
 122 #define OS_REASON_FLAG_CONSISTENT_FAILURE       0x40  /* Whatever caused this reason to be created will happen again */
 123 #define OS_REASON_FLAG_ONE_TIME_FAILURE         0x80  /* Whatever caused this reason to be created was a one time issue */
 124 #define OS_REASON_FLAG_NO_CRASHED_TID           0x100 /* Don't include the TID that processed the exit in the crash report */
 125
 126 /*
 127  * Set of flags that are allowed to be passed from userspace
 128  */
 129 #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)
 130
 131 /*
 132  * Macros to encode the exit reason namespace and first 32 bits of code in exception code
 133  * which is used by Report Crash as a hint. It should be only used as a hint since it
 134  * looses higher 32 bits of exit reason code.
 135  */
 136 #define ENCODE_OSR_NAMESPACE_TO_MACH_EXCEPTION_CODE(code, osr_namespace) \
 137         (code) = (code) | (((osr_namespace) & ((uint64_t)UINT32_MAX)) << 32)
 138 #define ENCODE_OSR_CODE_TO_MACH_EXCEPTION_CODE(code, osr_code) \
 139         (code) = (code) | ((osr_code) & ((uint64_t)UINT32_MAX))
 140
 141 #ifndef KERNEL
 142 /*
 143  * abort_with_reason: Used to exit the current process and pass along
 144  *                    specific information about why it is being terminated.
 145  *
 146  * Inputs:              args->reason_namespace - OS_REASON namespace specified for the reason
 147  *                      args->reason_code - code in the specified namespace for the reason
 148  *                      args->reason_string - additional string formatted information about the request
 149  *                      args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above).
 150  *
 151  * Outputs:             Does not return.
 152  */
 153 void abort_with_reason(uint32_t reason_namespace, uint64_t reason_code, const char *reason_string, uint64_t reason_flags) __attribute__((noreturn));
 154
 155 /*
 156  * abort_with_payload: Used to exit the current process and pass along
 157  *                     specific information about why it is being terminated. The payload pointer
 158  *                     should point to structured data that can be interpreted by the consumer of
 159  *                     exit reason information.
 160  *
 161  * Inputs:              args->reason_namespace - OS_REASON namespace specified for the reason
 162  *                      args->reason_code - code in the specified namespace for the reason
 163  *                      args->payload - pointer to payload structure in user space
 164  *                      args->payload_size - length of payload buffer (this will be truncated to EXIT_REASON_PAYLOAD_MAX_LEN)
 165  *                      args->reason_string - additional string formatted information about the request
 166  *                      args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above).
 167  *
 168  * Outputs:             Does not return.
 169  */
 170 void abort_with_payload(uint32_t reason_namespace, uint64_t reason_code, void *payload, uint32_t payload_size, const char *reason_string,
 171                                 uint64_t reason_flags) __attribute__((noreturn));
 172
 173 /*
 174  * terminate_with_reason: Used to terminate a specific process and pass along
 175  *                        specific information about why it is being terminated.
 176  *
 177  * Inputs:              args->pid - the PID of the process to be terminated
 178  *                      args->reason_namespace - OS_REASON namespace specified for the reason
 179  *                      args->reason_code - code in the specified namespace for the reason
 180  *                      args->reason_string - additional string formatted information about the request
 181  *                      args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above)
 182  *
 183  * Outputs:             EINVAL if the PID requested is the same as that of the calling process, invalid or the namespace provided is invalid.
 184  *                      ESRCH if we couldn't find a live process with the requested PID
 185  *                      EPERM if the caller is not privileged enough to kill the process with the requested PID
 186  *                      returns 0 otherwise
 187  */
 188 int terminate_with_reason(int pid, uint32_t reason_namespace, uint64_t reason_code, const char *reason_string, uint64_t reason_flags);
 189
 190 /*
 191  * terminate_with_payload: Used to terminate a specific process and pass along
 192  *                         specific information about why it is being terminated. The payload pointer
 193  *                         should point to structured data that can be interpreted by the consumer of
 194  *                         exit reason information.
 195  *
 196  * Inputs:              args->pid - the PID of the process to be terminated.
 197  *                      args->reason_namespace - OS_REASON namespace specified for the reason
 198  *                      args->reason_code - code in the specified namespace for the reason
 199  *                      args->payload - pointer to payload structure in user space
 200  *                      args->payload_size - length of payload buffer (this will be truncated to EXIT_REASON_PAYLOAD_MAX_LEN)
 201  *                      args->reason_string - additional string formatted information about the request
 202  *                      args->reason_flags - options requested for how the process should be terminated (see OS_REASON_FLAG_* above)
 203  *
 204  * Outputs:             EINVAL if the PID requested is the same as that of the calling process, is invalid or the namespace provided is invalid.
 205  *                      ESRCH if we couldn't find a live process with the requested PID
 206  *                      EPERM if the caller is not privileged enough to kill the process with the requested PID
 207  *                      returns 0 otherwise
 208  */
 209 int terminate_with_payload(int pid, uint32_t reason_namespace, uint64_t reason_code, void *payload, uint32_t payload_size,
 210                                 const char *reason_string, uint64_t reason_flags);
 211 #endif /* KERNEL */
 212
 213 /*
 214  * codesigning exit reasons
 215  */
 216 #define CODESIGNING_EXIT_REASON_TASKGATED_INVALID_SIG 1
 217 #define CODESIGNING_EXIT_REASON_INVALID_PAGE          2
 218 #define CODESIGNING_EXIT_REASON_TASK_ACCESS_PORT      3
 219
 220 /*
 221  * exec path specific exit reasons
 222  */
 223 #define EXEC_EXIT_REASON_BAD_MACHO          1
 224 #define EXEC_EXIT_REASON_SUGID_FAILURE      2
 225 #define EXEC_EXIT_REASON_ACTV_THREADSTATE   3
 226 #define EXEC_EXIT_REASON_STACK_ALLOC        4
 227 #define EXEC_EXIT_REASON_APPLE_STRING_INIT  5
 228 #define EXEC_EXIT_REASON_COPYOUT_STRINGS    6
 229 #define EXEC_EXIT_REASON_COPYOUT_DYNLINKER  7
 230 #define EXEC_EXIT_REASON_SECURITY_POLICY    8
 231 #define EXEC_EXIT_REASON_TASKGATED_OTHER    9
 232 #define EXEC_EXIT_REASON_FAIRPLAY_DECRYPT   10
 233 #define EXEC_EXIT_REASON_DECRYPT            11
 234 #define EXEC_EXIT_REASON_UPX                12
 235
 236 __END_DECLS
 237
 238 #endif /* _REASON_H_ */