1 /*- 2 * Copyright (c) 2016 Robert N. M. Watson 3 * All rights reserved. 4 * 5 * This software was developed by BAE Systems, the University of Cambridge 6 * Computer Laboratory, and Memorial University under DARPA/AFRL contract 7 * FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent Computing 8 * (TC) research program. 9 * 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions 12 * are met: 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in the 17 * documentation and/or other materials provided with the distribution. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29 * SUCH DAMAGE. 30 */ 31 32 #include <sys/cdefs.h> 33 __FBSDID("$FreeBSD$"); 34 35 #include <sys/param.h> 36 #include <sys/conf.h> 37 #include <sys/ctype.h> 38 #include <sys/kernel.h> 39 #include <sys/malloc.h> 40 #include <sys/module.h> 41 #include <sys/queue.h> 42 #include <sys/refcount.h> 43 44 #include <sys/dtrace.h> 45 #include <sys/dtrace_bsd.h> 46 47 #include <bsm/audit.h> 48 #include <bsm/audit_internal.h> 49 #include <bsm/audit_kevents.h> 50 51 #include <security/audit/audit.h> 52 #include <security/audit/audit_private.h> 53 54 /*- 55 * Audit DTrace provider: allow DTrace to request that audit records be 56 * generated for various audit events, and then expose those records (in 57 * various forms) to probes. The model is that each event type has two 58 * probes, which use the event's name to create the probe: 59 * 60 * - "commit" passes the kernel-internal (unserialised) kaudit_record 61 * synchronously (from the originating thread) of the record as we prepare 62 * to "commit" the record to the audit queue. 63 * 64 * - "bsm" also passes generated BSM, and executes asynchronously in the audit 65 * worker thread, once it has been extracted from the audit queue. This is 66 * the point at which an audit record would be enqueued to the trail on 67 * disk, or to pipes. 68 * 69 * These probes support very different goals. The former executes in the 70 * thread originating the record, making it easier to correlate other DTrace 71 * probe activity with the event described in the record. The latter gives 72 * access to BSM-formatted events (at a cost) allowing DTrace to extract BSM 73 * directly an alternative mechanism to the formal audit trail and audit 74 * pipes. 75 * 76 * To generate names for numeric event IDs, userspace will push the contents 77 * of /etc/security/audit_event into the kernel during audit setup, much as it 78 * does /etc/security/audit_class. We then create the probes for each of 79 * those mappings. If one (or both) of the probes are enabled, then we cause 80 * a record to be generated (as both normal audit preselection and audit pipes 81 * do), and catch it on the way out during commit. There are suitable hook 82 * functions in the audit code that this provider can register to catch 83 * various events in the audit-record life cycle. 84 * 85 * Further ponderings: 86 * 87 * - How do we want to handle events for which there are not names -- perhaps 88 * a catch-all probe for those events without mappings? 89 * 90 * - Should the evname code really be present even if DTrace isn't loaded...? 91 * Right now, we arrange that it is so that userspace can usefully maintain 92 * the list in case DTrace is later loaded (and to prevent userspace 93 * confusion). 94 * 95 * - Should we add an additional set of audit:class::commit probes that use 96 * event class names to match broader categories of events as specified in 97 * /etc/security/event_class? 98 * 99 * - If we pursue that last point, we will want to pass the name of the event 100 * into the probe explicitly (e.g., as arg0), since it would no longer be 101 * available as the probe function name. 102 */ 103 104 static int dtaudit_unload(void); 105 static void dtaudit_getargdesc(void *, dtrace_id_t, void *, 106 dtrace_argdesc_t *); 107 static void dtaudit_provide(void *, dtrace_probedesc_t *); 108 static void dtaudit_destroy(void *, dtrace_id_t, void *); 109 static void dtaudit_enable(void *, dtrace_id_t, void *); 110 static void dtaudit_disable(void *, dtrace_id_t, void *); 111 static void dtaudit_load(void *); 112 113 static dtrace_pattr_t dtaudit_attr = { 114 { DTRACE_STABILITY_EVOLVING, DTRACE_STABILITY_EVOLVING, DTRACE_CLASS_COMMON }, 115 { DTRACE_STABILITY_PRIVATE, DTRACE_STABILITY_PRIVATE, DTRACE_CLASS_UNKNOWN }, 116 { DTRACE_STABILITY_PRIVATE, DTRACE_STABILITY_PRIVATE, DTRACE_CLASS_UNKNOWN }, 117 { DTRACE_STABILITY_EVOLVING, DTRACE_STABILITY_EVOLVING, DTRACE_CLASS_COMMON }, 118 { DTRACE_STABILITY_EVOLVING, DTRACE_STABILITY_EVOLVING, DTRACE_CLASS_COMMON }, 119 }; 120 121 /* 122 * Strings for the "module" and "name" portions of the probe. The name of the 123 * audit event will be the "function" portion of the probe. All dtaudit 124 * probes therefore take the form audit:event:<event name>:commit. 125 */ 126 static char *dtaudit_module_str = "event"; 127 static char *dtaudit_name_commit_str = "commit"; 128 static char *dtaudit_name_bsm_str = "bsm"; 129 130 static dtrace_pops_t dtaudit_pops = { 131 .dtps_provide = dtaudit_provide, 132 .dtps_provide_module = NULL, 133 .dtps_enable = dtaudit_enable, 134 .dtps_disable = dtaudit_disable, 135 .dtps_suspend = NULL, 136 .dtps_resume = NULL, 137 .dtps_getargdesc = dtaudit_getargdesc, 138 .dtps_getargval = NULL, 139 .dtps_usermode = NULL, 140 .dtps_destroy = dtaudit_destroy 141 }; 142 143 static dtrace_provider_id_t dtaudit_id; 144 145 /* 146 * Because looking up entries in the event-to-name mapping is quite expensive, 147 * maintain a global flag tracking whether any dtaudit probes are enabled. If 148 * not, don't bother doing all that work whenever potential queries about 149 * events turn up during preselection or commit. 150 */ 151 static uint_t dtaudit_probes_enabled; 152 153 /* 154 * Check dtaudit policy for the event to see whether this is an event we would 155 * like to preselect (i.e., cause an audit record to be generated for). To 156 * minimise probe effect when not used at all, we not only check for the probe 157 * on the individual event, but also a global flag indicating that at least 158 * one probe is enabled, before acquiring locks, searching lists, etc. 159 * 160 * If the event is selected, return an evname_elem reference to be stored in 161 * the audit record, which we can use later to avoid further lookups. The 162 * contents of the evname_elem must be sufficiently stable so as to not risk 163 * race conditions here. 164 * 165 * Currently, we take an interest only in the 'event' argument, but in the 166 * future might want to support other types of record selection tied to 167 * additional probe types (e.g., event clases). 168 * 169 * XXXRW: Should we have a catch-all probe here for events without registered 170 * names? 171 */ 172 static void * 173 dtaudit_preselect(au_id_t auid, au_event_t event, au_class_t class) 174 { 175 struct evname_elem *ene; 176 int probe_enabled; 177 178 /* 179 * NB: Lockless reads here may return a slightly stale value; this is 180 * considered better than acquiring a lock, however. 181 */ 182 if (!dtaudit_probes_enabled) 183 return (NULL); 184 ene = au_evnamemap_lookup(event); 185 if (ene == NULL) 186 return (NULL); 187 188 /* 189 * See if either of the two probes for the audit event are enabled. 190 * 191 * NB: Lock also not acquired here -- but perhaps it wouldn't matter 192 * given that we've already used the list lock above? 193 * 194 * XXXRW: Alternatively, au_evnamemap_lookup() could return these 195 * values while holding the list lock...? 196 */ 197 probe_enabled = ene->ene_commit_probe_enabled || 198 ene->ene_bsm_probe_enabled; 199 if (!probe_enabled) 200 return (NULL); 201 return ((void *)ene); 202 } 203 204 /* 205 * Commit probe pre-BSM. Fires the probe but also checks to see if we should 206 * ask the audit framework to call us again with BSM arguments in the audit 207 * worker thread. 208 * 209 * XXXRW: Should we have a catch-all probe here for events without registered 210 * names? 211 */ 212 static int 213 dtaudit_commit(struct kaudit_record *kar, au_id_t auid, au_event_t event, 214 au_class_t class, int sorf) 215 { 216 char ene_name_lower[EVNAMEMAP_NAME_SIZE]; 217 struct evname_elem *ene; 218 int i; 219 220 ene = (struct evname_elem *)kar->k_dtaudit_state; 221 if (ene == NULL) 222 return (0); 223 224 /* 225 * Process a possibly registered commit probe. 226 */ 227 if (ene->ene_commit_probe_enabled) { 228 /* 229 * XXXRW: Lock ene to provide stability to the name string. A 230 * bit undesirable! We may want another locking strategy 231 * here. At least we don't run the DTrace probe under the 232 * lock. 233 * 234 * XXXRW: We provide the struct audit_record pointer -- but 235 * perhaps should provide the kaudit_record pointer? 236 */ 237 EVNAME_LOCK(ene); 238 for (i = 0; i < sizeof(ene_name_lower); i++) 239 ene_name_lower[i] = tolower(ene->ene_name[i]); 240 EVNAME_UNLOCK(ene); 241 dtrace_probe(ene->ene_commit_probe_id, 242 (uintptr_t)ene_name_lower, (uintptr_t)&kar->k_ar, 0, 0, 0); 243 } 244 245 /* 246 * Return the state of the BSM probe to the caller. 247 */ 248 return (ene->ene_bsm_probe_enabled); 249 } 250 251 /* 252 * Commit probe post-BSM. 253 * 254 * XXXRW: Should we have a catch-all probe here for events without registered 255 * names? 256 */ 257 static void 258 dtaudit_bsm(struct kaudit_record *kar, au_id_t auid, au_event_t event, 259 au_class_t class, int sorf, void *bsm_data, size_t bsm_len) 260 { 261 char ene_name_lower[EVNAMEMAP_NAME_SIZE]; 262 struct evname_elem *ene; 263 int i; 264 265 ene = (struct evname_elem *)kar->k_dtaudit_state; 266 if (ene == NULL) 267 return; 268 if (!(ene->ene_bsm_probe_enabled)) 269 return; 270 271 /* 272 * XXXRW: Lock ene to provide stability to the name string. A bit 273 * undesirable! We may want another locking strategy here. At least 274 * we don't run the DTrace probe under the lock. 275 * 276 * XXXRW: We provide the struct audit_record pointer -- but perhaps 277 * should provide the kaudit_record pointer? 278 */ 279 EVNAME_LOCK(ene); 280 for (i = 0; i < sizeof(ene_name_lower); i++) 281 ene_name_lower[i] = tolower(ene->ene_name[i]); 282 EVNAME_UNLOCK(ene); 283 dtrace_probe(ene->ene_bsm_probe_id, (uintptr_t)ene_name_lower, 284 (uintptr_t)&kar->k_ar, (uintptr_t)bsm_data, (uintptr_t)bsm_len, 285 0); 286 } 287 288 /* 289 * A very simple provider: argument types are identical across all probes: the 290 * kaudit_record, plus a BSM pointer and length. 291 */ 292 static void 293 dtaudit_getargdesc(void *arg, dtrace_id_t id, void *parg, 294 dtrace_argdesc_t *desc) 295 { 296 struct evname_elem *ene; 297 const char *p; 298 299 ene = (struct evname_elem *)parg; 300 p = NULL; 301 switch (desc->dtargd_ndx) { 302 case 0: 303 /* Audit event name. */ 304 p = "char *"; 305 break; 306 307 case 1: 308 /* In-kernel audit record. */ 309 p = "struct audit_record *"; 310 break; 311 312 case 2: 313 /* BSM data, if present. */ 314 if (id == ene->ene_bsm_probe_id) 315 p = "const void *"; 316 else 317 desc->dtargd_ndx = DTRACE_ARGNONE; 318 break; 319 320 case 3: 321 /* BSM length, if present. */ 322 if (id == ene->ene_bsm_probe_id) 323 p = "size_t"; 324 else 325 desc->dtargd_ndx = DTRACE_ARGNONE; 326 break; 327 328 default: 329 desc->dtargd_ndx = DTRACE_ARGNONE; 330 break; 331 } 332 if (p != NULL) 333 strlcpy(desc->dtargd_native, p, sizeof(desc->dtargd_native)); 334 } 335 336 /* 337 * Callback from the event-to-name mapping code when performing 338 * evname_foreach(). Note that we may update the entry, so the foreach code 339 * must have a write lock. However, as the synchronisation model is private 340 * to the evname code, we cannot easily assert it here. 341 * 342 * XXXRW: How do we want to handle event rename / collision issues here -- 343 * e.g., if userspace was using a name to point to one event number, and then 344 * changes it so that the name points at another? For now, paper over this by 345 * skipping event numbers that are already registered, and likewise skipping 346 * names that are already registered. However, this could lead to confusing 347 * behaviour so possibly needs to be resolved in the longer term. 348 */ 349 static void 350 dtaudit_au_evnamemap_callback(struct evname_elem *ene) 351 { 352 char ene_name_lower[EVNAMEMAP_NAME_SIZE]; 353 int i; 354 355 /* 356 * DTrace, by convention, has lower-case probe names. However, the 357 * in-kernel event-to-name mapping table must maintain event-name case 358 * as submitted by userspace. Create a temporary lower-case version 359 * here, away from the fast path, to use when exposing the event name 360 * to DTrace as part of the name of a probe. 361 * 362 * NB: Convert the entire array, including the terminating nul, 363 * because these strings are short and it's more work not to. If they 364 * become long, we might feel more guilty about this sloppiness! 365 */ 366 for (i = 0; i < sizeof(ene_name_lower); i++) 367 ene_name_lower[i] = tolower(ene->ene_name[i]); 368 369 /* 370 * Don't register a new probe if this event number already has an 371 * associated commit probe -- or if another event has already 372 * registered this name. 373 * 374 * XXXRW: There is an argument that if multiple numeric events match 375 * a single name, they should all be exposed to the same named probe. 376 * In particular, we should perhaps use a probe ID returned by this 377 * lookup and just stick that in the saved probe ID? 378 */ 379 if ((ene->ene_commit_probe_id == 0) && 380 (dtrace_probe_lookup(dtaudit_id, dtaudit_module_str, 381 ene_name_lower, dtaudit_name_commit_str) == 0)) { 382 383 /* 384 * Create the commit probe. 385 * 386 * NB: We don't declare any extra stack frames because stack() 387 * will just return the path to the audit commit code, which 388 * is not really interesting anyway. 389 * 390 * We pass in the pointer to the evnam_elem entry so that we 391 * can easily change its enabled flag in the probe 392 * enable/disable interface. 393 */ 394 ene->ene_commit_probe_id = dtrace_probe_create(dtaudit_id, 395 dtaudit_module_str, ene_name_lower, 396 dtaudit_name_commit_str, 0, ene); 397 } 398 399 /* 400 * Don't register a new probe if this event number already has an 401 * associated bsm probe -- or if another event has already 402 * registered this name. 403 * 404 * XXXRW: There is an argument that if multiple numeric events match 405 * a single name, they should all be exposed to the same named probe. 406 * In particular, we should perhaps use a probe ID returned by this 407 * lookup and just stick that in the saved probe ID? 408 */ 409 if ((ene->ene_bsm_probe_id == 0) && 410 (dtrace_probe_lookup(dtaudit_id, dtaudit_module_str, 411 ene_name_lower, dtaudit_name_bsm_str) == 0)) { 412 413 /* 414 * Create the bsm probe. 415 * 416 * NB: We don't declare any extra stack frames because stack() 417 * will just return the path to the audit commit code, which 418 * is not really interesting anyway. 419 * 420 * We pass in the pointer to the evnam_elem entry so that we 421 * can easily change its enabled flag in the probe 422 * enable/disable interface. 423 */ 424 ene->ene_bsm_probe_id = dtrace_probe_create(dtaudit_id, 425 dtaudit_module_str, ene_name_lower, dtaudit_name_bsm_str, 426 0, ene); 427 } 428 } 429 430 static void 431 dtaudit_provide(void *arg, dtrace_probedesc_t *desc) 432 { 433 434 /* 435 * Walk all registered number-to-name mapping entries, and ensure each 436 * is properly registered. 437 */ 438 au_evnamemap_foreach(dtaudit_au_evnamemap_callback); 439 } 440 441 static void 442 dtaudit_destroy(void *arg, dtrace_id_t id, void *parg) 443 { 444 } 445 446 static void 447 dtaudit_enable(void *arg, dtrace_id_t id, void *parg) 448 { 449 struct evname_elem *ene; 450 451 ene = parg; 452 KASSERT(ene->ene_commit_probe_id == id || ene->ene_bsm_probe_id == id, 453 ("%s: probe ID mismatch (%u, %u != %u)", __func__, 454 ene->ene_commit_probe_id, ene->ene_bsm_probe_id, id)); 455 456 if (id == ene->ene_commit_probe_id) 457 ene->ene_commit_probe_enabled = 1; 458 else 459 ene->ene_bsm_probe_enabled = 1; 460 refcount_acquire(&dtaudit_probes_enabled); 461 } 462 463 static void 464 dtaudit_disable(void *arg, dtrace_id_t id, void *parg) 465 { 466 struct evname_elem *ene; 467 468 ene = parg; 469 KASSERT(ene->ene_commit_probe_id == id || ene->ene_bsm_probe_id == id, 470 ("%s: probe ID mismatch (%u, %u != %u)", __func__, 471 ene->ene_commit_probe_id, ene->ene_bsm_probe_id, id)); 472 473 if (id == ene->ene_commit_probe_id) 474 ene->ene_commit_probe_enabled = 0; 475 else 476 ene->ene_bsm_probe_enabled = 0; 477 (void)refcount_release(&dtaudit_probes_enabled); 478 } 479 480 static void 481 dtaudit_load(void *dummy) 482 { 483 484 if (dtrace_register("audit", &dtaudit_attr, DTRACE_PRIV_USER, NULL, 485 &dtaudit_pops, NULL, &dtaudit_id) != 0) 486 return; 487 dtaudit_hook_preselect = dtaudit_preselect; 488 dtaudit_hook_commit = dtaudit_commit; 489 dtaudit_hook_bsm = dtaudit_bsm; 490 } 491 492 static int 493 dtaudit_unload(void) 494 { 495 int error; 496 497 dtaudit_hook_preselect = NULL; 498 dtaudit_hook_commit = NULL; 499 dtaudit_hook_bsm = NULL; 500 if ((error = dtrace_unregister(dtaudit_id)) != 0) 501 return (error); 502 return (0); 503 } 504 505 static int 506 dtaudit_modevent(module_t mod __unused, int type, void *data __unused) 507 { 508 int error = 0; 509 510 switch (type) { 511 case MOD_LOAD: 512 case MOD_UNLOAD: 513 case MOD_SHUTDOWN: 514 break; 515 516 default: 517 error = EOPNOTSUPP; 518 break; 519 } 520 521 return (error); 522 } 523 524 SYSINIT(dtaudit_load, SI_SUB_DTRACE_PROVIDER, SI_ORDER_ANY, dtaudit_load, 525 NULL); 526 SYSUNINIT(dtaudit_unload, SI_SUB_DTRACE_PROVIDER, SI_ORDER_ANY, 527 dtaudit_unload, NULL); 528 529 DEV_MODULE(dtaudit, dtaudit_modevent, NULL); 530 MODULE_VERSION(dtaudit, 1); 531 MODULE_DEPEND(dtaudit, dtrace, 1, 1, 1); 532 MODULE_DEPEND(dtaudit, opensolaris, 1, 1, 1); 533