bsd/kern/kern_ktrace.c

   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>
  59 char *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
  71 kern_return_t ktrace_background_available_notify_user(void);
  72
  73 static 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  */
  80 static enum ktrace_state ktrace_state = KTRACE_STATE_OFF;
  81
  82 /* The true owner of ktrace, checked by ktrace_access_check(). */
  83 static uint64_t ktrace_owning_unique_id = 0;
  84 static 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  */
  90 static uint64_t ktrace_bg_unique_id = 0;
  91 static pid_t ktrace_bg_pid = 0;
  92
  93 /* The name of the last process to configure ktrace. */
  94 static char ktrace_last_owner_execname[MAXCOMLEN + 1] = { 0 };
  95
  96 /*
  97  * Which subsystems of ktrace (currently kdebug and kperf) are active.
  98  */
  99 static 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  */
 108 static bool should_notify_on_init = true;
 109
 110 /* Set the owning process of ktrace. */
 111 static void ktrace_set_owning_proc(proc_t p);
 112
 113 /* Reset ktrace ownership back to unowned. */
 114 static void ktrace_release_ownership(void);
 115
 116 /* Make the background tool the owner of ktrace. */
 117 static 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  */
 127 bool ktrace_keep_ownership_on_reset = false;
 128
 129 /* Whether the kernel is the owner of ktrace. */
 130 bool ktrace_owner_kernel = false;
 131
 132 /* Allow user space to unset the owning pid and potentially reset ktrace. */
 133 static 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  */
 139 int 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  */
 145 static bool ktrace_single_threaded = false;
 146
 147 void
 148 ktrace_lock(void)
 149 {
 150         if (!ktrace_single_threaded) {
 151                 lck_mtx_lock(ktrace_mtx);
 152         }
 153 }
 154
 155 void
 156 ktrace_unlock(void)
 157 {
 158         if (!ktrace_single_threaded) {
 159                 lck_mtx_unlock(ktrace_mtx);
 160         }
 161 }
 162
 163 void
 164 ktrace_assert_lock_held(void)
 165 {
 166         if (!ktrace_single_threaded) {
 167                 lck_mtx_assert(ktrace_mtx, LCK_MTX_ASSERT_OWNED);
 168         }
 169 }
 170
 171 void
 172 ktrace_start_single_threaded(void)
 173 {
 174         ktrace_single_threaded = true;
 175 }
 176
 177 void
 178 ktrace_end_single_threaded(void)
 179 {
 180         ktrace_single_threaded = false;
 181 }
 182
 183 static void
 184 ktrace_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
 210 void
 211 ktrace_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
 225 static void
 226 ktrace_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
 245 bool
 246 ktrace_background_active(void)
 247 {
 248         return (ktrace_state == KTRACE_STATE_BG);
 249 }
 250
 251 int
 252 ktrace_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. */
 265 static void
 266 ktrace_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
 291 int
 292 ktrace_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
 330 void
 331 ktrace_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
 339 int
 340 ktrace_get_owning_pid(void)
 341 {
 342         ktrace_assert_lock_held();
 343
 344         ktrace_ownership_maintenance();
 345         return ktrace_owning_pid;
 346 }
 347
 348 void
 349 ktrace_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
 376 static errno_t
 377 ktrace_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
 418 void
 419 ktrace_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
 427 int
 428 ktrace_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
 457 static void
 458 ktrace_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
 489 static void
 490 ktrace_release_ownership(void)
 491 {
 492         ktrace_owning_unique_id = 0;
 493         ktrace_owning_pid = 0;
 494 }
 495
 496 #define SYSCTL_INIT_BACKGROUND (1)
 497
 498 static int ktrace_sysctl SYSCTL_HANDLER_ARGS;
 499
 500 SYSCTL_NODE(, OID_AUTO, ktrace, CTLFLAG_RW | CTLFLAG_LOCKED, 0, "ktrace");
 501
 502 SYSCTL_UINT(_ktrace, OID_AUTO, state, CTLFLAG_RD | CTLFLAG_LOCKED,
 503             &ktrace_state, 0,
 504             "");
 505
 506 SYSCTL_INT(_ktrace, OID_AUTO, owning_pid, CTLFLAG_RD | CTLFLAG_LOCKED,
 507            &ktrace_owning_pid, 0,
 508            "pid of the process that owns ktrace");
 509
 510 SYSCTL_INT(_ktrace, OID_AUTO, background_pid, CTLFLAG_RD | CTLFLAG_LOCKED,
 511            &ktrace_bg_pid, 0,
 512            "pid of the background ktrace tool");
 513
 514 SYSCTL_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
 518 SYSCTL_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
 522 static int
 523 ktrace_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
 549 out:
 550         ktrace_unlock();
 551         return ret;
 552 }
 553
 554 /* This should only be called from the bootstrap thread. */
 555 void
 556 ktrace_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 }