1 /* 2 * Copyright (c) 2004 Apple Computer, Inc. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of Apple Computer, Inc. ("Apple") nor the names of 14 * its contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND 18 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 * ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR 21 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 25 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 26 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27 * POSSIBILITY OF SUCH DAMAGE. 28 * 29 * $P4: //depot/projects/trustedbsd/openbsm/bsm/libbsm.h#30 $ 30 */ 31 32 #ifndef _LIBBSM_H_ 33 #define _LIBBSM_H_ 34 35 /* 36 * NB: definitions, etc., marked with "OpenSSH compatibility" were introduced 37 * solely to allow OpenSSH to compile; Darwin/Apple code should not use them. 38 */ 39 40 #include <sys/types.h> 41 #include <sys/cdefs.h> 42 43 #include <inttypes.h> /* Required for audit.h. */ 44 #include <time.h> /* Required for clock_t on Linux. */ 45 46 #include <bsm/audit.h> 47 #include <bsm/audit_record.h> 48 49 #include <stdio.h> 50 51 #ifdef __APPLE__ 52 #include <mach/mach.h> /* audit_token_t */ 53 #endif 54 55 /* 56 * Size parsed token vectors for execve(2) arguments and environmental 57 * variables. Note: changing these sizes affects the ABI of the token 58 * structure, and as the token structure is often placed in the caller stack, 59 * this is undesirable. 60 */ 61 #define AUDIT_MAX_ARGS 128 62 #define AUDIT_MAX_ENV 128 63 64 /* 65 * Arguments to au_preselect(3). 66 */ 67 #define AU_PRS_USECACHE 0 68 #define AU_PRS_REREAD 1 69 70 #define AU_PRS_SUCCESS 1 71 #define AU_PRS_FAILURE 2 72 #define AU_PRS_BOTH (AU_PRS_SUCCESS|AU_PRS_FAILURE) 73 74 #define AUDIT_EVENT_FILE "/etc/security/audit_event" 75 #define AUDIT_CLASS_FILE "/etc/security/audit_class" 76 #define AUDIT_CONTROL_FILE "/etc/security/audit_control" 77 #define AUDIT_USER_FILE "/etc/security/audit_user" 78 79 #define DIR_CONTROL_ENTRY "dir" 80 #define MINFREE_CONTROL_ENTRY "minfree" 81 #define FILESZ_CONTROL_ENTRY "filesz" 82 #define FLAGS_CONTROL_ENTRY "flags" 83 #define NA_CONTROL_ENTRY "naflags" 84 #define POLICY_CONTROL_ENTRY "policy" 85 86 #define AU_CLASS_NAME_MAX 8 87 #define AU_CLASS_DESC_MAX 72 88 #define AU_EVENT_NAME_MAX 30 89 #define AU_EVENT_DESC_MAX 50 90 #define AU_USER_NAME_MAX 50 91 #define AU_LINE_MAX 256 92 #define MAX_AUDITSTRING_LEN 256 93 #define BSM_TEXTBUFSZ MAX_AUDITSTRING_LEN /* OpenSSH compatibility */ 94 95 /* 96 * Arguments to au_close(3). 97 */ 98 #define AU_TO_NO_WRITE 0 /* Abandon audit record. */ 99 #define AU_TO_WRITE 1 /* Commit audit record. */ 100 101 __BEGIN_DECLS 102 struct au_event_ent { 103 au_event_t ae_number; 104 char *ae_name; 105 char *ae_desc; 106 au_class_t ae_class; 107 }; 108 typedef struct au_event_ent au_event_ent_t; 109 110 struct au_class_ent { 111 char *ac_name; 112 au_class_t ac_class; 113 char *ac_desc; 114 }; 115 typedef struct au_class_ent au_class_ent_t; 116 117 struct au_user_ent { 118 char *au_name; 119 au_mask_t au_always; 120 au_mask_t au_never; 121 }; 122 typedef struct au_user_ent au_user_ent_t; 123 __END_DECLS 124 125 #define ADD_TO_MASK(m, c, sel) do { \ 126 if (sel & AU_PRS_SUCCESS) \ 127 (m)->am_success |= c; \ 128 if (sel & AU_PRS_FAILURE) \ 129 (m)->am_failure |= c; \ 130 } while (0) 131 132 #define SUB_FROM_MASK(m, c, sel) do { \ 133 if (sel & AU_PRS_SUCCESS) \ 134 (m)->am_success &= ((m)->am_success ^ c); \ 135 if (sel & AU_PRS_FAILURE) \ 136 (m)->am_failure &= ((m)->am_failure ^ c); \ 137 } while (0) 138 139 #define ADDMASK(m, v) do { \ 140 (m)->am_success |= (v)->am_success; \ 141 (m)->am_failure |= (v)->am_failure; \ 142 } while(0) 143 144 #define SUBMASK(m, v) do { \ 145 (m)->am_success &= ((m)->am_success ^ (v)->am_success); \ 146 (m)->am_failure &= ((m)->am_failure ^ (v)->am_failure); \ 147 } while(0) 148 149 __BEGIN_DECLS 150 151 typedef struct au_tid32 { 152 u_int32_t port; 153 u_int32_t addr; 154 } au_tid32_t; 155 156 typedef struct au_tid64 { 157 u_int64_t port; 158 u_int32_t addr; 159 } au_tid64_t; 160 161 typedef struct au_tidaddr32 { 162 u_int32_t port; 163 u_int32_t type; 164 u_int32_t addr[4]; 165 } au_tidaddr32_t; 166 167 /* 168 * argument # 1 byte 169 * argument value 4 bytes/8 bytes (32-bit/64-bit value) 170 * text length 2 bytes 171 * text N bytes + 1 terminating NULL byte 172 */ 173 typedef struct { 174 u_char no; 175 u_int32_t val; 176 u_int16_t len; 177 char *text; 178 } au_arg32_t; 179 180 typedef struct { 181 u_char no; 182 u_int64_t val; 183 u_int16_t len; 184 char *text; 185 } au_arg64_t; 186 187 /* 188 * how to print 1 byte 189 * basic unit 1 byte 190 * unit count 1 byte 191 * data items (depends on basic unit) 192 */ 193 typedef struct { 194 u_char howtopr; 195 u_char bu; 196 u_char uc; 197 u_char *data; 198 } au_arb_t; 199 200 /* 201 * file access mode 4 bytes 202 * owner user ID 4 bytes 203 * owner group ID 4 bytes 204 * file system ID 4 bytes 205 * node ID 8 bytes 206 * device 4 bytes/8 bytes (32-bit/64-bit) 207 */ 208 typedef struct { 209 u_int32_t mode; 210 u_int32_t uid; 211 u_int32_t gid; 212 u_int32_t fsid; 213 u_int64_t nid; 214 u_int32_t dev; 215 } au_attr32_t; 216 217 typedef struct { 218 u_int32_t mode; 219 u_int32_t uid; 220 u_int32_t gid; 221 u_int32_t fsid; 222 u_int64_t nid; 223 u_int64_t dev; 224 } au_attr64_t; 225 226 /* 227 * count 4 bytes 228 * text count null-terminated string(s) 229 */ 230 typedef struct { 231 u_int32_t count; 232 char *text[AUDIT_MAX_ARGS]; 233 } au_execarg_t; 234 235 /* 236 * count 4 bytes 237 * text count null-terminated string(s) 238 */ 239 typedef struct { 240 u_int32_t count; 241 char *text[AUDIT_MAX_ENV]; 242 } au_execenv_t; 243 244 /* 245 * status 4 bytes 246 * return value 4 bytes 247 */ 248 typedef struct { 249 u_int32_t status; 250 u_int32_t ret; 251 } au_exit_t; 252 253 /* 254 * seconds of time 4 bytes 255 * milliseconds of time 4 bytes 256 * file name length 2 bytes 257 * file pathname N bytes + 1 terminating NULL byte 258 */ 259 typedef struct { 260 u_int32_t s; 261 u_int32_t ms; 262 u_int16_t len; 263 char *name; 264 } au_file_t; 265 266 267 /* 268 * number groups 2 bytes 269 * group list N * 4 bytes 270 */ 271 typedef struct { 272 u_int16_t no; 273 u_int32_t list[AUDIT_MAX_GROUPS]; 274 } au_groups_t; 275 276 /* 277 * record byte count 4 bytes 278 * version # 1 byte [2] 279 * event type 2 bytes 280 * event modifier 2 bytes 281 * seconds of time 4 bytes/8 bytes (32-bit/64-bit value) 282 * milliseconds of time 4 bytes/8 bytes (32-bit/64-bit value) 283 */ 284 typedef struct { 285 u_int32_t size; 286 u_char version; 287 u_int16_t e_type; 288 u_int16_t e_mod; 289 u_int32_t s; 290 u_int32_t ms; 291 } au_header32_t; 292 293 /* 294 * record byte count 4 bytes 295 * version # 1 byte [2] 296 * event type 2 bytes 297 * event modifier 2 bytes 298 * address type/length 1 byte (XXX: actually, 4 bytes) 299 * machine address 4 bytes/16 bytes (IPv4/IPv6 address) 300 * seconds of time 4 bytes/8 bytes (32/64-bits) 301 * nanoseconds of time 4 bytes/8 bytes (32/64-bits) 302 */ 303 typedef struct { 304 u_int32_t size; 305 u_char version; 306 u_int16_t e_type; 307 u_int16_t e_mod; 308 u_int32_t ad_type; 309 u_int32_t addr[4]; 310 u_int32_t s; 311 u_int32_t ms; 312 } au_header32_ex_t; 313 314 typedef struct { 315 u_int32_t size; 316 u_char version; 317 u_int16_t e_type; 318 u_int16_t e_mod; 319 u_int64_t s; 320 u_int64_t ms; 321 } au_header64_t; 322 323 typedef struct { 324 u_int32_t size; 325 u_char version; 326 u_int16_t e_type; 327 u_int16_t e_mod; 328 u_int32_t ad_type; 329 u_int32_t addr[4]; 330 u_int64_t s; 331 u_int64_t ms; 332 } au_header64_ex_t; 333 334 /* 335 * internet address 4 bytes 336 */ 337 typedef struct { 338 u_int32_t addr; 339 } au_inaddr_t; 340 341 /* 342 * type 4 bytes 343 * internet address 16 bytes 344 */ 345 typedef struct { 346 u_int32_t type; 347 u_int32_t addr[4]; 348 } au_inaddr_ex_t; 349 350 /* 351 * version and ihl 1 byte 352 * type of service 1 byte 353 * length 2 bytes 354 * id 2 bytes 355 * offset 2 bytes 356 * ttl 1 byte 357 * protocol 1 byte 358 * checksum 2 bytes 359 * source address 4 bytes 360 * destination address 4 bytes 361 */ 362 typedef struct { 363 u_char version; 364 u_char tos; 365 u_int16_t len; 366 u_int16_t id; 367 u_int16_t offset; 368 u_char ttl; 369 u_char prot; 370 u_int16_t chksm; 371 u_int32_t src; 372 u_int32_t dest; 373 } au_ip_t; 374 375 /* 376 * object ID type 1 byte 377 * object ID 4 bytes 378 */ 379 typedef struct { 380 u_char type; 381 u_int32_t id; 382 } au_ipc_t; 383 384 /* 385 * owner user ID 4 bytes 386 * owner group ID 4 bytes 387 * creator user ID 4 bytes 388 * creator group ID 4 bytes 389 * access mode 4 bytes 390 * slot sequence # 4 bytes 391 * key 4 bytes 392 */ 393 typedef struct { 394 u_int32_t uid; 395 u_int32_t gid; 396 u_int32_t puid; 397 u_int32_t pgid; 398 u_int32_t mode; 399 u_int32_t seq; 400 u_int32_t key; 401 } au_ipcperm_t; 402 403 /* 404 * port IP address 2 bytes 405 */ 406 typedef struct { 407 u_int16_t port; 408 } au_iport_t; 409 410 /* 411 * length 2 bytes 412 * data length bytes 413 */ 414 typedef struct { 415 u_int16_t size; 416 char *data; 417 } au_opaque_t; 418 419 /* 420 * path length 2 bytes 421 * path N bytes + 1 terminating NULL byte 422 */ 423 typedef struct { 424 u_int16_t len; 425 char *path; 426 } au_path_t; 427 428 /* 429 * audit ID 4 bytes 430 * effective user ID 4 bytes 431 * effective group ID 4 bytes 432 * real user ID 4 bytes 433 * real group ID 4 bytes 434 * process ID 4 bytes 435 * session ID 4 bytes 436 * terminal ID 437 * port ID 4 bytes/8 bytes (32-bit/64-bit value) 438 * machine address 4 bytes 439 */ 440 typedef struct { 441 u_int32_t auid; 442 u_int32_t euid; 443 u_int32_t egid; 444 u_int32_t ruid; 445 u_int32_t rgid; 446 u_int32_t pid; 447 u_int32_t sid; 448 au_tid32_t tid; 449 } au_proc32_t; 450 451 typedef struct { 452 u_int32_t auid; 453 u_int32_t euid; 454 u_int32_t egid; 455 u_int32_t ruid; 456 u_int32_t rgid; 457 u_int32_t pid; 458 u_int32_t sid; 459 au_tid64_t tid; 460 } au_proc64_t; 461 462 /* 463 * audit ID 4 bytes 464 * effective user ID 4 bytes 465 * effective group ID 4 bytes 466 * real user ID 4 bytes 467 * real group ID 4 bytes 468 * process ID 4 bytes 469 * session ID 4 bytes 470 * terminal ID 471 * port ID 4 bytes/8 bytes (32-bit/64-bit value) 472 * type 4 bytes 473 * machine address 16 bytes 474 */ 475 typedef struct { 476 u_int32_t auid; 477 u_int32_t euid; 478 u_int32_t egid; 479 u_int32_t ruid; 480 u_int32_t rgid; 481 u_int32_t pid; 482 u_int32_t sid; 483 au_tidaddr32_t tid; 484 } au_proc32ex_t; 485 486 /* 487 * error status 1 byte 488 * return value 4 bytes/8 bytes (32-bit/64-bit value) 489 */ 490 typedef struct { 491 u_char status; 492 u_int32_t ret; 493 } au_ret32_t; 494 495 typedef struct { 496 u_char err; 497 u_int64_t val; 498 } au_ret64_t; 499 500 /* 501 * sequence number 4 bytes 502 */ 503 typedef struct { 504 u_int32_t seqno; 505 } au_seq_t; 506 507 /* 508 * socket type 2 bytes 509 * local port 2 bytes 510 * local Internet address 4 bytes 511 * remote port 2 bytes 512 * remote Internet address 4 bytes 513 */ 514 typedef struct { 515 u_int16_t type; 516 u_int16_t l_port; 517 u_int32_t l_addr; 518 u_int16_t r_port; 519 u_int32_t r_addr; 520 } au_socket_t; 521 522 /* 523 * socket type 2 bytes 524 * local port 2 bytes 525 * address type/length 4 bytes 526 * local Internet address 4 bytes/16 bytes (IPv4/IPv6 address) 527 * remote port 4 bytes 528 * address type/length 4 bytes 529 * remote Internet address 4 bytes/16 bytes (IPv4/IPv6 address) 530 */ 531 typedef struct { 532 u_int16_t type; 533 u_int16_t l_port; 534 u_int32_t l_ad_type; 535 u_int32_t l_addr; 536 u_int32_t r_port; 537 u_int32_t r_ad_type; 538 u_int32_t r_addr; 539 } au_socket_ex32_t; 540 541 /* 542 * socket family 2 bytes 543 * local port 2 bytes 544 * socket address 4 bytes/16 bytes (IPv4/IPv6 address) 545 */ 546 typedef struct { 547 u_int16_t family; 548 u_int16_t port; 549 u_int32_t addr; 550 } au_socketinet32_t; 551 552 /* 553 * socket family 2 bytes 554 * path 104 bytes 555 */ 556 typedef struct { 557 u_int16_t family; 558 char path[104]; 559 } au_socketunix_t; 560 561 /* 562 * audit ID 4 bytes 563 * effective user ID 4 bytes 564 * effective group ID 4 bytes 565 * real user ID 4 bytes 566 * real group ID 4 bytes 567 * process ID 4 bytes 568 * session ID 4 bytes 569 * terminal ID 570 * port ID 4 bytes/8 bytes (32-bit/64-bit value) 571 * machine address 4 bytes 572 */ 573 typedef struct { 574 u_int32_t auid; 575 u_int32_t euid; 576 u_int32_t egid; 577 u_int32_t ruid; 578 u_int32_t rgid; 579 u_int32_t pid; 580 u_int32_t sid; 581 au_tid32_t tid; 582 } au_subject32_t; 583 584 typedef struct { 585 u_int32_t auid; 586 u_int32_t euid; 587 u_int32_t egid; 588 u_int32_t ruid; 589 u_int32_t rgid; 590 u_int32_t pid; 591 u_int32_t sid; 592 au_tid64_t tid; 593 } au_subject64_t; 594 595 /* 596 * audit ID 4 bytes 597 * effective user ID 4 bytes 598 * effective group ID 4 bytes 599 * real user ID 4 bytes 600 * real group ID 4 bytes 601 * process ID 4 bytes 602 * session ID 4 bytes 603 * terminal ID 604 * port ID 4 bytes/8 bytes (32-bit/64-bit value) 605 * type 4 bytes 606 * machine address 16 bytes 607 */ 608 typedef struct { 609 u_int32_t auid; 610 u_int32_t euid; 611 u_int32_t egid; 612 u_int32_t ruid; 613 u_int32_t rgid; 614 u_int32_t pid; 615 u_int32_t sid; 616 au_tidaddr32_t tid; 617 } au_subject32ex_t; 618 619 /* 620 * text length 2 bytes 621 * text N bytes + 1 terminating NULL byte 622 */ 623 typedef struct { 624 u_int16_t len; 625 char *text; 626 } au_text_t; 627 628 typedef struct { 629 u_int32_t ident; 630 u_int16_t filter; 631 u_int16_t flags; 632 u_int32_t fflags; 633 u_int32_t data; 634 } au_kevent_t; 635 636 typedef struct { 637 u_int16_t length; 638 char *data; 639 } au_invalid_t; 640 641 /* 642 * trailer magic number 2 bytes 643 * record byte count 4 bytes 644 */ 645 typedef struct { 646 u_int16_t magic; 647 u_int32_t count; 648 } au_trailer_t; 649 650 struct tokenstr { 651 u_char id; 652 u_char *data; 653 size_t len; 654 union { 655 au_arg32_t arg32; 656 au_arg64_t arg64; 657 au_arb_t arb; 658 au_attr32_t attr32; 659 au_attr64_t attr64; 660 au_execarg_t execarg; 661 au_execenv_t execenv; 662 au_exit_t exit; 663 au_file_t file; 664 au_groups_t grps; 665 au_header32_t hdr32; 666 au_header32_ex_t hdr32_ex; 667 au_header64_t hdr64; 668 au_header64_ex_t hdr64_ex; 669 au_inaddr_t inaddr; 670 au_inaddr_ex_t inaddr_ex; 671 au_ip_t ip; 672 au_ipc_t ipc; 673 au_ipcperm_t ipcperm; 674 au_iport_t iport; 675 au_opaque_t opaque; 676 au_path_t path; 677 au_proc32_t proc32; 678 au_proc64_t proc64; 679 au_proc32ex_t proc32_ex; 680 au_ret32_t ret32; 681 au_ret64_t ret64; 682 au_seq_t seq; 683 au_socket_t socket; 684 au_socket_ex32_t socket_ex32; 685 au_socketinet32_t sockinet32; 686 au_socketunix_t sockunix; 687 au_subject32_t subj32; 688 au_subject64_t subj64; 689 au_subject32ex_t subj32_ex; 690 au_text_t text; 691 au_kevent_t kevent; 692 au_invalid_t invalid; 693 au_trailer_t trail; 694 } tt; /* The token is one of the above types */ 695 }; 696 697 typedef struct tokenstr tokenstr_t; 698 699 int audit_submit(short au_event, au_id_t auid, 700 char status, int reterr, const char *fmt, ...); 701 702 /* 703 * Functions relating to querying audit class information. 704 */ 705 void setauclass(void); 706 void endauclass(void); 707 struct au_class_ent *getauclassent(void); 708 struct au_class_ent *getauclassent_r(au_class_ent_t *class_int); 709 struct au_class_ent *getauclassnam(const char *name); 710 struct au_class_ent *getauclassnam_r(au_class_ent_t *class_int, 711 const char *name); 712 struct au_class_ent *getauclassnum(au_class_t class_number); 713 struct au_class_ent *getauclassnum_r(au_class_ent_t *class_int, 714 au_class_t class_number); 715 716 /* 717 * Functions relating to querying audit control information. 718 */ 719 void setac(void); 720 void endac(void); 721 int getacdir(char *name, int len); 722 int getacmin(int *min_val); 723 int getacfilesz(size_t *size_val); 724 int getacflg(char *auditstr, int len); 725 int getacna(char *auditstr, int len); 726 int getacpol(char *auditstr, size_t len); 727 int getauditflagsbin(char *auditstr, au_mask_t *masks); 728 int getauditflagschar(char *auditstr, au_mask_t *masks, 729 int verbose); 730 int au_preselect(au_event_t event, au_mask_t *mask_p, 731 int sorf, int flag); 732 ssize_t au_poltostr(long policy, size_t maxsize, char *buf); 733 int au_strtopol(const char *polstr, long *policy); 734 735 /* 736 * Functions relating to querying audit event information. 737 */ 738 void setauevent(void); 739 void endauevent(void); 740 struct au_event_ent *getauevent(void); 741 struct au_event_ent *getauevent_r(struct au_event_ent *e); 742 struct au_event_ent *getauevnam(const char *name); 743 struct au_event_ent *getauevnam_r(struct au_event_ent *e, 744 const char *name); 745 struct au_event_ent *getauevnum(au_event_t event_number); 746 struct au_event_ent *getauevnum_r(struct au_event_ent *e, 747 au_event_t event_number); 748 au_event_t *getauevnonam(const char *event_name); 749 au_event_t *getauevnonam_r(au_event_t *ev, 750 const char *event_name); 751 752 /* 753 * Functions relating to querying audit user information. 754 */ 755 void setauuser(void); 756 void endauuser(void); 757 struct au_user_ent *getauuserent(void); 758 struct au_user_ent *getauuserent_r(struct au_user_ent *u); 759 struct au_user_ent *getauusernam(const char *name); 760 struct au_user_ent *getauusernam_r(struct au_user_ent *u, 761 const char *name); 762 int au_user_mask(char *username, au_mask_t *mask_p); 763 int getfauditflags(au_mask_t *usremask, 764 au_mask_t *usrdmask, au_mask_t *lastmask); 765 766 /* 767 * Functions for reading and printing records and tokens from audit trails. 768 */ 769 int au_read_rec(FILE *fp, u_char **buf); 770 int au_fetch_tok(tokenstr_t *tok, u_char *buf, int len); 771 //XXX The following interface has different prototype from BSM 772 void au_print_tok(FILE *outfp, tokenstr_t *tok, 773 char *del, char raw, char sfrm); 774 __END_DECLS 775 776 /* 777 * The remaining APIs are associated with Apple's BSM implementation, in 778 * particular as relates to Mach IPC auditing and triggers passed via Mach 779 * IPC. 780 */ 781 #ifdef __APPLE__ 782 #include <sys/appleapiopts.h> 783 784 /************************************************************************** 785 ************************************************************************** 786 ** The following definitions, functions, etc., are NOT officially 787 ** supported: they may be changed or removed in the future. Do not use 788 ** them unless you are prepared to cope with that eventuality. 789 ************************************************************************** 790 **************************************************************************/ 791 792 #ifdef __APPLE_API_PRIVATE 793 #define __BSM_INTERNAL_NOTIFY_KEY "com.apple.audit.change" 794 #endif /* __APPLE_API_PRIVATE */ 795 796 /* 797 * au_get_state() return values 798 * XXX use AUC_* values directly instead (<bsm/audit.h>); AUDIT_OFF and 799 * AUDIT_ON are deprecated and WILL be removed. 800 */ 801 #ifdef __APPLE_API_PRIVATE 802 #define AUDIT_OFF AUC_NOAUDIT 803 #define AUDIT_ON AUC_AUDITING 804 #endif /* __APPLE_API_PRIVATE */ 805 #endif /* !__APPLE__ */ 806 807 /* 808 * Error return codes for audit_set_terminal_id(), audit_write() and its 809 * brethren. We have 255 (not including kAUNoErr) to play with. 810 * 811 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 812 */ 813 enum { 814 kAUNoErr = 0, 815 kAUBadParamErr = -66049, 816 kAUStatErr, 817 kAUSysctlErr, 818 kAUOpenErr, 819 kAUMakeSubjectTokErr, 820 kAUWriteSubjectTokErr, 821 kAUWriteCallerTokErr, 822 kAUMakeReturnTokErr, 823 kAUWriteReturnTokErr, 824 kAUCloseErr, 825 kAUMakeTextTokErr, 826 kAULastErr 827 }; 828 829 #ifdef __APPLE__ 830 /* 831 * Error return codes for au_get_state() and/or its private support 832 * functions. These codes are designed to be compatible with the 833 * NOTIFY_STATUS_* codes defined in <notify.h> but non-overlapping. 834 * Any changes to notify(3) may cause these values to change in future. 835 * 836 * AU_UNIMPL should never happen unless you've changed your system software 837 * without rebooting. Shame on you. 838 */ 839 #ifdef __APPLE_API_PRIVATE 840 #define AU_UNIMPL NOTIFY_STATUS_FAILED + 1 /* audit unimplemented */ 841 #endif /* __APPLE_API_PRIVATE */ 842 #endif /* !__APPLE__ */ 843 844 __BEGIN_DECLS 845 /* 846 * XXX This prototype should be in audit_record.h 847 * 848 * au_free_token() 849 * 850 * @summary - au_free_token() deallocates a token_t created by any of 851 * the au_to_*() BSM API functions. 852 * 853 * The BSM API generally manages deallocation of token_t objects. However, 854 * if au_write() is passed a bad audit descriptor, the token_t * parameter 855 * will be left untouched. In that case, the caller can deallocate the 856 * token_t using au_free_token() if desired. This is, in fact, what 857 * audit_write() does, in keeping with the existing memory management model 858 * of the BSM API. 859 * 860 * @param tok - A token_t * generated by one of the au_to_*() BSM API 861 * calls. For convenience, tok may be NULL, in which case 862 * au_free_token() returns immediately. 863 * 864 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 865 */ 866 void au_free_token(token_t *tok); 867 868 /* 869 * Lightweight check to determine if auditing is enabled. If a client 870 * wants to use this to govern whether an entire series of audit calls 871 * should be made--as in the common case of a caller building a set of 872 * tokens, then writing them--it should cache the audit status in a local 873 * variable. This call always returns the current state of auditing. 874 * 875 * @return - AUC_AUDITING or AUC_NOAUDIT if no error occurred. 876 * Otherwise the function can return any of the errno values defined for 877 * setaudit(2), or AU_UNIMPL if audit does not appear to be supported by 878 * the system. 879 * 880 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 881 */ 882 int au_get_state(void); 883 __END_DECLS 884 885 /* OpenSSH compatibility */ 886 int cannot_audit(int); 887 888 __BEGIN_DECLS 889 /* 890 * audit_set_terminal_id() 891 * 892 * @summary - audit_set_terminal_id() fills in an au_tid_t struct, which is 893 * used in audit session initialization by processes like /usr/bin/login. 894 * 895 * @param tid - A pointer to an au_tid_t struct. 896 * 897 * @return - kAUNoErr on success; kAUBadParamErr if tid is NULL, kAUStatErr 898 * or kAUSysctlErr if one of the underlying system calls fails (a message 899 * is sent to the system log in those cases). 900 * 901 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 902 */ 903 int audit_set_terminal_id(au_tid_t *tid); 904 905 /* 906 * BEGIN au_write() WRAPPERS 907 * 908 * The following calls all wrap the existing BSM API. They use the 909 * provided subject information, if any, to construct the subject token 910 * required for every log message. They use the provided return/error 911 * value(s), if any, to construct the success/failure indication required 912 * for every log message. They only permit one "miscellaneous" token, 913 * which should contain the event-specific logging information mandated by 914 * CAPP. 915 * 916 * All these calls assume the caller has previously determined that 917 * auditing is enabled by calling au_get_state(). 918 */ 919 920 /* 921 * audit_write() 922 * 923 * @summary - audit_write() is the basis for the other audit_write_*() 924 * calls. Performs a basic write of an audit record (subject, additional 925 * info, success/failure). Note that this call only permits logging one 926 * caller-specified token; clients needing to log more flexibly must use 927 * the existing BSM API (au_open(), et al.) directly. 928 * 929 * Note on memory management: audit_write() guarantees that the token_t *s 930 * passed to it will be deallocated whether or not the underlying write to 931 * the audit log succeeded. This addresses an inconsistency in the 932 * underlying BSM API in which token_t *s are usually but not always 933 * deallocated. 934 * 935 * @param event_code - The code for the event being logged. This should 936 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 937 * 938 * @param subject - A token_t * generated by au_to_subject(), 939 * au_to_subject32(), au_to_subject64(), or au_to_me(). If no subject is 940 * required, subject should be NULL. 941 * 942 * @param misctok - A token_t * generated by one of the au_to_*() BSM API 943 * calls. This should correspond to the additional information required by 944 * CAPP for the event being audited. If no additional information is 945 * required, misctok should be NULL. 946 * 947 * @param retval - The return value to be logged for this event. This 948 * should be 0 (zero) for success, otherwise the value is event-specific. 949 * 950 * @param errcode - Any error code associated with the return value (e.g., 951 * errno or h_errno). If there was no error, errcode should be 0 (zero). 952 * 953 * @return - The status of the call: 0 (zero) on success, else one of the 954 * kAU*Err values defined above. 955 * 956 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 957 */ 958 int audit_write(short event_code, token_t *subject, token_t *misctok, 959 char retval, int errcode); 960 961 /* 962 * audit_write_success() 963 * 964 * @summary - audit_write_success() records an auditable event that did not 965 * encounter an error. The interface is designed to require as little 966 * direct use of the au_to_*() API as possible. It builds a subject token 967 * from the information passed in and uses that to invoke audit_write(). 968 * A subject, as defined by CAPP, is a process acting on the user's behalf. 969 * 970 * If the subject information is the same as the current process, use 971 * au_write_success_self(). 972 * 973 * @param event_code - The code for the event being logged. This should 974 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 975 * 976 * @param misctok - A token_t * generated by one of the au_to_*() BSM API 977 * calls. This should correspond to the additional information required by 978 * CAPP for the event being audited. If no additional information is 979 * required, misctok should be NULL. 980 * 981 * @param auid - The subject's audit ID. 982 * 983 * @param euid - The subject's effective user ID. 984 * 985 * @param egid - The subject's effective group ID. 986 * 987 * @param ruid - The subject's real user ID. 988 * 989 * @param rgid - The subject's real group ID. 990 * 991 * @param pid - The subject's process ID. 992 * 993 * @param sid - The subject's session ID. 994 * 995 * @param tid - The subject's terminal ID. 996 * 997 * @return - The status of the call: 0 (zero) on success, else one of the 998 * kAU*Err values defined above. 999 * 1000 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1001 */ 1002 int audit_write_success(short event_code, token_t *misctok, au_id_t auid, 1003 uid_t euid, gid_t egid, uid_t ruid, gid_t rgid, pid_t pid, 1004 au_asid_t sid, au_tid_t *tid); 1005 1006 /* 1007 * audit_write_success_self() 1008 * 1009 * @summary - Similar to audit_write_success(), but used when the subject 1010 * (process) is owned and operated by the auditable user him/herself. 1011 * 1012 * @param event_code - The code for the event being logged. This should 1013 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 1014 * 1015 * @param misctok - A token_t * generated by one of the au_to_*() BSM API 1016 * calls. This should correspond to the additional information required by 1017 * CAPP for the event being audited. If no additional information is 1018 * required, misctok should be NULL. 1019 * 1020 * @return - The status of the call: 0 (zero) on success, else one of the 1021 * kAU*Err values defined above. 1022 * 1023 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1024 */ 1025 int audit_write_success_self(short event_code, token_t *misctok); 1026 1027 /* 1028 * audit_write_failure() 1029 * 1030 * @summary - audit_write_failure() records an auditable event that 1031 * encountered an error. The interface is designed to require as little 1032 * direct use of the au_to_*() API as possible. It builds a subject token 1033 * from the information passed in and uses that to invoke audit_write(). 1034 * A subject, as defined by CAPP, is a process acting on the user's behalf. 1035 * 1036 * If the subject information is the same as the current process, use 1037 * au_write_failure_self(). 1038 * 1039 * @param event_code - The code for the event being logged. This should 1040 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 1041 * 1042 * @param errmsg - A text message providing additional information about 1043 * the event being audited. 1044 * 1045 * @param errret - A numerical value providing additional information about 1046 * the error. This is intended to store the value of errno or h_errno if 1047 * it's relevant. This can be 0 (zero) if no additional information is 1048 * available. 1049 * 1050 * @param auid - The subject's audit ID. 1051 * 1052 * @param euid - The subject's effective user ID. 1053 * 1054 * @param egid - The subject's effective group ID. 1055 * 1056 * @param ruid - The subject's real user ID. 1057 * 1058 * @param rgid - The subject's real group ID. 1059 * 1060 * @param pid - The subject's process ID. 1061 * 1062 * @param sid - The subject's session ID. 1063 * 1064 * @param tid - The subject's terminal ID. 1065 * 1066 * @return - The status of the call: 0 (zero) on success, else one of the 1067 * kAU*Err values defined above. 1068 * 1069 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1070 */ 1071 int audit_write_failure(short event_code, char *errmsg, int errret, 1072 au_id_t auid, uid_t euid, gid_t egid, uid_t ruid, gid_t rgid, 1073 pid_t pid, au_asid_t sid, au_tid_t *tid); 1074 1075 /* 1076 * audit_write_failure_self() 1077 * 1078 * @summary - Similar to audit_write_failure(), but used when the subject 1079 * (process) is owned and operated by the auditable user him/herself. 1080 * 1081 * @param event_code - The code for the event being logged. This should 1082 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 1083 * 1084 * @param errmsg - A text message providing additional information about 1085 * the event being audited. 1086 * 1087 * @param errret - A numerical value providing additional information about 1088 * the error. This is intended to store the value of errno or h_errno if 1089 * it's relevant. This can be 0 (zero) if no additional information is 1090 * available. 1091 * 1092 * @return - The status of the call: 0 (zero) on success, else one of the 1093 * kAU*Err values defined above. 1094 * 1095 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1096 */ 1097 int audit_write_failure_self(short event_code, char *errmsg, int errret); 1098 1099 /* 1100 * audit_write_failure_na() 1101 * 1102 * @summary - audit_write_failure_na() records errors during login. Such 1103 * errors are implicitly non-attributable (i.e., not ascribable to any user). 1104 * 1105 * @param event_code - The code for the event being logged. This should 1106 * be one of the AUE_ values in /usr/include/bsm/audit_uevents.h. 1107 * 1108 * @param errmsg - A text message providing additional information about 1109 * the event being audited. 1110 * 1111 * @param errret - A numerical value providing additional information about 1112 * the error. This is intended to store the value of errno or h_errno if 1113 * it's relevant. This can be 0 (zero) if no additional information is 1114 * available. 1115 * 1116 * @param euid - The subject's effective user ID. 1117 * 1118 * @param egid - The subject's effective group ID. 1119 * 1120 * @param pid - The subject's process ID. 1121 * 1122 * @param tid - The subject's terminal ID. 1123 * 1124 * @return - The status of the call: 0 (zero) on success, else one of the 1125 * kAU*Err values defined above. 1126 * 1127 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1128 */ 1129 int audit_write_failure_na(short event_code, char *errmsg, int errret, 1130 uid_t euid, gid_t egid, pid_t pid, au_tid_t *tid); 1131 1132 /* END au_write() WRAPPERS */ 1133 1134 #ifdef __APPLE__ 1135 /* 1136 * audit_token_to_au32() 1137 * 1138 * @summary - Extract information from an audit_token_t, used to identify 1139 * Mach tasks and senders of Mach messages as subjects to the audit system. 1140 * audit_tokent_to_au32() is the only method that should be used to parse 1141 * an audit_token_t, since its internal representation may change over 1142 * time. A pointer parameter may be NULL if that information is not 1143 * needed. 1144 * 1145 * @param atoken - the audit token containing the desired information 1146 * 1147 * @param auidp - Pointer to a uid_t; on return will be set to the task or 1148 * sender's audit user ID 1149 * 1150 * @param euidp - Pointer to a uid_t; on return will be set to the task or 1151 * sender's effective user ID 1152 * 1153 * @param egidp - Pointer to a gid_t; on return will be set to the task or 1154 * sender's effective group ID 1155 * 1156 * @param ruidp - Pointer to a uid_t; on return will be set to the task or 1157 * sender's real user ID 1158 * 1159 * @param rgidp - Pointer to a gid_t; on return will be set to the task or 1160 * sender's real group ID 1161 * 1162 * @param pidp - Pointer to a pid_t; on return will be set to the task or 1163 * sender's process ID 1164 * 1165 * @param asidp - Pointer to an au_asid_t; on return will be set to the 1166 * task or sender's audit session ID 1167 * 1168 * @param tidp - Pointer to an au_tid_t; on return will be set to the task 1169 * or sender's terminal ID 1170 * 1171 * XXXRW: In Apple's bsm-8, these are marked __APPLE_API_PRIVATE. 1172 */ 1173 void audit_token_to_au32( 1174 audit_token_t atoken, 1175 uid_t *auidp, 1176 uid_t *euidp, 1177 gid_t *egidp, 1178 uid_t *ruidp, 1179 gid_t *rgidp, 1180 pid_t *pidp, 1181 au_asid_t *asidp, 1182 au_tid_t *tidp); 1183 #endif /* !__APPLE__ */ 1184 1185 __END_DECLS 1186 1187 #endif /* !_LIBBSM_H_ */ 1188