1/*
2 * Copyright (c) 2015-2017 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/*
30 * This file manages the ownership of ktrace and its subsystems, like kdebug
31 * and kperf, as well as the overall state of the system, whether it is in
32 * foreground or background mode.
33 *
34 * When unconfigured or in background mode, any root process can take ownership
35 * of ktrace and configure it, changing the state to foreground and, in the case
36 * of a transition out of background, resetting the background configuration.
37 *
38 * When in foreground mode, if the owning process is still running, only it may
39 * configure ktrace. If it exits, ktrace keeps running but any root process can
40 * change the configuration. When ktrace is reset, the state changes back to
41 * unconfigured and a notification is sent on the ktrace_background host special
42 * port.
43 *
44 * If a process has set itself as the background tool, using the init_background
45 * sysctl, it can configure ktrace only when ktrace is off or already in
46 * background mode. The first attempt to configure ktrace by the background pid
47 * when it is off results in the transition to background mode.
48 */
49
50#include <sys/ktrace.h>
51
52#include <mach/host_priv.h>
53#include <mach/mach_types.h>
54#include <mach/ktrace_background.h>
55
56#include <sys/kauth.h>
57#include <sys/priv.h>
58#include <sys/proc.h>
59char *proc_name_address(void *p);
60#include <sys/sysctl.h>
61#include <sys/vm.h>
62
63#include <kern/locks.h>
64#include <kern/assert.h>
65
66#include <sys/kdebug.h>
67#include <kperf/kperf.h>
68
69#include <kern/host.h>
70
71kern_return_t ktrace_background_available_notify_user(void);
72
73static lck_mtx_t *ktrace_mtx;
74
75/*
76 * The overall state of ktrace, whether it is unconfigured, in foreground mode,
77 * or in background mode. The state determines which processes can configure
78 * ktrace.
79 */
80static enum ktrace_state ktrace_state = KTRACE_STATE_OFF;
81
82/* The true owner of ktrace, checked by ktrace_access_check(). */
83static uint64_t ktrace_owning_unique_id = 0;
84static pid_t ktrace_owning_pid = 0;
85
86/*
87 * The background pid of ktrace, automatically made the owner when
88 * transitioning to background mode.
89 */
90static uint64_t ktrace_bg_unique_id = 0;
91static pid_t ktrace_bg_pid = 0;
92
93/* The name of the last process to configure ktrace. */
94static char ktrace_last_owner_execname[MAXCOMLEN + 1] = { 0 };
95
96/*
97 * Which subsystems of ktrace (currently kdebug and kperf) are active.
98 */
99static uint32_t ktrace_active_mask = 0;
100
101/*
102 * At boot or when a daemon has been newly loaded, it's necessary to bootstrap
103 * user space background tools by sending a background available notification
104 * when the init_background sysctl is made.
105 *
106 * Background tools must be RunAtLoad daemons.
107 */
108static bool should_notify_on_init = true;
109
110/* Set the owning process of ktrace. */
111static void ktrace_set_owning_proc(proc_t p);
112
113/* Reset ktrace ownership back to unowned. */
114static void ktrace_release_ownership(void);
115
116/* Make the background tool the owner of ktrace. */
117static void ktrace_promote_background(void);
118
119/*
120 * If user space sets a pid manually (through kperf "blessing"), ktrace should
121 * not treat resets as releasing ownership. At that point, ownership is only
122 * released when the owner is set to an invalid pid.
123 *
124 * This is managed by the user space-oriented function ktrace_set_owning_pid
125 * and ktrace_unset_owning_pid.
126 */
127bool ktrace_keep_ownership_on_reset = false;
128
129/* Whether the kernel is the owner of ktrace. */
130bool ktrace_owner_kernel = false;
131
132/* Allow user space to unset the owning pid and potentially reset ktrace. */
133static void ktrace_set_invalid_owning_pid(void);
134
135/*
136 * This flag allows any root process to set a new ktrace owner. It is
137 * currently used by Instruments.
138 */
139int ktrace_root_set_owner_allowed = 0;
140
141/*
142 * If ktrace is guaranteed that it's the only thread running on the system
143 * (e.g., during boot or wake) this flag disables locking requirements.
144 */
145static bool ktrace_single_threaded = false;
146
147void
148ktrace_lock(void)
149{
150 if (!ktrace_single_threaded) {
151 lck_mtx_lock(ktrace_mtx);
152 }
153}
154
155void
156ktrace_unlock(void)
157{
158 if (!ktrace_single_threaded) {
159 lck_mtx_unlock(ktrace_mtx);
160 }
161}
162
163void
164ktrace_assert_lock_held(void)
165{
166 if (!ktrace_single_threaded) {
167 lck_mtx_assert(ktrace_mtx, LCK_MTX_ASSERT_OWNED);
168 }
169}
170
171void
172ktrace_start_single_threaded(void)
173{
174 ktrace_single_threaded = true;
175}
176
177void
178ktrace_end_single_threaded(void)
179{
180 ktrace_single_threaded = false;
181}
182
183static void
184ktrace_reset_internal(uint32_t reset_mask)
185{
186 if (!ktrace_keep_ownership_on_reset) {
187 ktrace_active_mask &= ~reset_mask;
188 }
189
190 if (reset_mask & KTRACE_KPERF) {
191 kperf_reset();
192 }
193 if (reset_mask & KTRACE_KDEBUG) {
194 kdebug_reset();
195 }
196
197 if (ktrace_active_mask == 0) {
198 if (ktrace_state == KTRACE_STATE_FG) {
199 /* transition from foreground to background */
200 ktrace_promote_background();
201 } else if (ktrace_state == KTRACE_STATE_BG) {
202 /* background tool is resetting ktrace */
203 should_notify_on_init = true;
204 ktrace_release_ownership();
205 ktrace_state = KTRACE_STATE_OFF;
206 }
207 }
208}
209
210void
211ktrace_reset(uint32_t reset_mask)
212{
213 ktrace_assert_lock_held();
214
215 if (ktrace_active_mask == 0) {
216 if (!ktrace_keep_ownership_on_reset) {
217 assert(ktrace_state == KTRACE_STATE_OFF);
218 }
219 return;
220 }
221
222 ktrace_reset_internal(reset_mask);
223}
224
225static void
226ktrace_promote_background(void)
227{
228 assert(ktrace_state != KTRACE_STATE_BG);
229
230 /*
231 * Remember to send a background available notification on the next init
232 * if the notification failed (meaning no task holds the receive right
233 * for the host special port).
234 */
235 if (ktrace_background_available_notify_user() == KERN_FAILURE) {
236 should_notify_on_init = true;
237 } else {
238 should_notify_on_init = false;
239 }
240
241 ktrace_release_ownership();
242 ktrace_state = KTRACE_STATE_OFF;
243}
244
245bool
246ktrace_background_active(void)
247{
248 return (ktrace_state == KTRACE_STATE_BG);
249}
250
251int
252ktrace_read_check(void)
253{
254 ktrace_assert_lock_held();
255
256 if (proc_uniqueid(current_proc()) == ktrace_owning_unique_id)
257 {
258 return 0;
259 }
260
261 return kauth_cred_issuser(kauth_cred_get()) ? 0 : EPERM;
262}
263
264/* If an owning process has exited, reset the ownership. */
265static void
266ktrace_ownership_maintenance(void)
267{
268 ktrace_assert_lock_held();
269
270 /* do nothing if ktrace is not owned */
271 if (ktrace_owning_unique_id == 0) {
272 return;
273 }
274
275 /* reset ownership if process cannot be found */
276
277 proc_t owning_proc = proc_find(ktrace_owning_pid);
278
279 if (owning_proc != NULL) {
280 /* make sure the pid was not recycled */
281 if (proc_uniqueid(owning_proc) != ktrace_owning_unique_id) {
282 ktrace_release_ownership();
283 }
284
285 proc_rele(owning_proc);
286 } else {
287 ktrace_release_ownership();
288 }
289}
290
291int
292ktrace_configure(uint32_t config_mask)
293{
294 ktrace_assert_lock_held();
295 assert(config_mask != 0);
296
297 proc_t p = current_proc();
298
299 /* if process clearly owns ktrace, allow */
300 if (proc_uniqueid(p) == ktrace_owning_unique_id) {
301 ktrace_active_mask |= config_mask;
302 return 0;
303 }
304
305 /* background configure while foreground is active is not allowed */
306 if (proc_uniqueid(p) == ktrace_bg_unique_id &&
307 ktrace_state == KTRACE_STATE_FG)
308 {
309 return EBUSY;
310 }
311
312 ktrace_ownership_maintenance();
313
314 /* allow process to gain control when unowned or background */
315 if (ktrace_owning_unique_id == 0 || ktrace_state == KTRACE_STATE_BG) {
316 if (!kauth_cred_issuser(kauth_cred_get())) {
317 return EPERM;
318 }
319
320 ktrace_owner_kernel = false;
321 ktrace_set_owning_proc(p);
322 ktrace_active_mask |= config_mask;
323 return 0;
324 }
325
326 /* owned by an existing, different process */
327 return EBUSY;
328}
329
330void
331ktrace_disable(enum ktrace_state state_to_match)
332{
333 if (ktrace_state == state_to_match) {
334 kernel_debug_disable();
335 kperf_sampling_disable();
336 }
337}
338
339int
340ktrace_get_owning_pid(void)
341{
342 ktrace_assert_lock_held();
343
344 ktrace_ownership_maintenance();
345 return ktrace_owning_pid;
346}
347
348void
349ktrace_kernel_configure(uint32_t config_mask)
350{
351 assert(ktrace_single_threaded == true);
352
353 if (ktrace_owner_kernel) {
354 ktrace_active_mask |= config_mask;
355 return;
356 }
357
358 if (ktrace_state != KTRACE_STATE_OFF) {
359 if (ktrace_active_mask & config_mask & KTRACE_KPERF) {
360 kperf_reset();
361 }
362 if (ktrace_active_mask & config_mask & KTRACE_KDEBUG) {
363 kdebug_reset();
364 }
365 }
366
367 ktrace_owner_kernel = true;
368 ktrace_active_mask |= config_mask;
369 ktrace_state = KTRACE_STATE_FG;
370
371 ktrace_release_ownership();
372 strlcpy(ktrace_last_owner_execname, "kernel_task",
373 sizeof(ktrace_last_owner_execname));
374}
375
376static errno_t
377ktrace_init_background(void)
378{
379 int err = 0;
380
381 ktrace_assert_lock_held();
382
383 if ((err = priv_check_cred(kauth_cred_get(), PRIV_KTRACE_BACKGROUND, 0))) {
384 return err;
385 }
386
387 /*
388 * When a background tool first checks in, send a notification if ktrace
389 * is available.
390 */
391 if (should_notify_on_init) {
392 if (ktrace_state == KTRACE_STATE_OFF) {
393 /*
394 * This notification can only fail if a process does not
395 * hold the receive right for the host special port.
396 * Return an error and don't make the current process
397 * the background tool.
398 */
399 if (ktrace_background_available_notify_user() == KERN_FAILURE) {
400 return EINVAL;
401 }
402 }
403 should_notify_on_init = false;
404 }
405
406 proc_t p = current_proc();
407
408 ktrace_bg_unique_id = proc_uniqueid(p);
409 ktrace_bg_pid = proc_pid(p);
410
411 if (ktrace_state == KTRACE_STATE_BG) {
412 ktrace_set_owning_proc(p);
413 }
414
415 return 0;
416}
417
418void
419ktrace_set_invalid_owning_pid(void)
420{
421 if (ktrace_keep_ownership_on_reset) {
422 ktrace_keep_ownership_on_reset = false;
423 ktrace_reset_internal(ktrace_active_mask);
424 }
425}
426
427int
428ktrace_set_owning_pid(int pid)
429{
430 ktrace_assert_lock_held();
431
432 /* allow user space to successfully unset owning pid */
433 if (pid == -1) {
434 ktrace_set_invalid_owning_pid();
435 return 0;
436 }
437
438 /* use ktrace_reset or ktrace_release_ownership, not this */
439 if (pid == 0) {
440 ktrace_set_invalid_owning_pid();
441 return EINVAL;
442 }
443
444 proc_t p = proc_find(pid);
445 if (!p) {
446 ktrace_set_invalid_owning_pid();
447 return ESRCH;
448 }
449
450 ktrace_keep_ownership_on_reset = true;
451 ktrace_set_owning_proc(p);
452
453 proc_rele(p);
454 return 0;
455}
456
457static void
458ktrace_set_owning_proc(proc_t p)
459{
460 ktrace_assert_lock_held();
461 assert(p != NULL);
462
463 if (ktrace_state != KTRACE_STATE_FG) {
464 if (proc_uniqueid(p) == ktrace_bg_unique_id) {
465 ktrace_state = KTRACE_STATE_BG;
466 } else {
467 if (ktrace_state == KTRACE_STATE_BG) {
468 if (ktrace_active_mask & KTRACE_KPERF) {
469 kperf_reset();
470 }
471 if (ktrace_active_mask & KTRACE_KDEBUG) {
472 kdebug_reset();
473 }
474
475 ktrace_active_mask = 0;
476 }
477 ktrace_state = KTRACE_STATE_FG;
478 should_notify_on_init = false;
479 }
480 }
481
482 ktrace_owner_kernel = false;
483 ktrace_owning_unique_id = proc_uniqueid(p);
484 ktrace_owning_pid = proc_pid(p);
485 strlcpy(ktrace_last_owner_execname, proc_name_address(p),
486 sizeof(ktrace_last_owner_execname));
487}
488
489static void
490ktrace_release_ownership(void)
491{
492 ktrace_owning_unique_id = 0;
493 ktrace_owning_pid = 0;
494}
495
496#define SYSCTL_INIT_BACKGROUND (1)
497
498static int ktrace_sysctl SYSCTL_HANDLER_ARGS;
499
500SYSCTL_NODE(, OID_AUTO, ktrace, CTLFLAG_RW | CTLFLAG_LOCKED, 0, "ktrace");
501
502SYSCTL_UINT(_ktrace, OID_AUTO, state, CTLFLAG_RD | CTLFLAG_LOCKED,
503 &ktrace_state, 0,
504 "");
505
506SYSCTL_INT(_ktrace, OID_AUTO, owning_pid, CTLFLAG_RD | CTLFLAG_LOCKED,
507 &ktrace_owning_pid, 0,
508 "pid of the process that owns ktrace");
509
510SYSCTL_INT(_ktrace, OID_AUTO, background_pid, CTLFLAG_RD | CTLFLAG_LOCKED,
511 &ktrace_bg_pid, 0,
512 "pid of the background ktrace tool");
513
514SYSCTL_STRING(_ktrace, OID_AUTO, configured_by, CTLFLAG_RD | CTLFLAG_LOCKED,
515 ktrace_last_owner_execname, 0,
516 "execname of process that last configured ktrace");
517
518SYSCTL_PROC(_ktrace, OID_AUTO, init_background, CTLFLAG_RW | CTLFLAG_LOCKED,
519 (void *)SYSCTL_INIT_BACKGROUND, sizeof(int),
520 ktrace_sysctl, "I", "initialize calling process as background");
521
522static int
523ktrace_sysctl SYSCTL_HANDLER_ARGS
524{
525#pragma unused(oidp, arg2)
526 int ret = 0;
527 uintptr_t type = (uintptr_t)arg1;
528
529 ktrace_lock();
530
531 if (!kauth_cred_issuser(kauth_cred_get())) {
532 ret = EPERM;
533 goto out;
534 }
535
536 if (type == SYSCTL_INIT_BACKGROUND) {
537 if (req->newptr != USER_ADDR_NULL) {
538 ret = ktrace_init_background();
539 goto out;
540 } else {
541 ret = EINVAL;
542 goto out;
543 }
544 } else {
545 ret = EINVAL;
546 goto out;
547 }
548
549out:
550 ktrace_unlock();
551 return ret;
552}
553
554/* This should only be called from the bootstrap thread. */
555void
556ktrace_init(void)
557{
558 static lck_grp_attr_t *lock_grp_attr = NULL;
559 static lck_grp_t *lock_grp = NULL;
560 static bool initialized = false;
561
562 if (initialized) {
563 return;
564 }
565
566 lock_grp_attr = lck_grp_attr_alloc_init();
567 lock_grp = lck_grp_alloc_init("ktrace", lock_grp_attr);
568 lck_grp_attr_free(lock_grp_attr);
569
570 ktrace_mtx = lck_mtx_alloc_init(lock_grp, LCK_ATTR_NULL);
571 assert(ktrace_mtx != NULL);;
572 initialized = true;
573}
574