1.\"- 2.\" Copyright (c) 2005-2007 Robert N. M. Watson 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.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/libbsm.3#13 $ 27.\" 28.Dd April 19, 2005 29.Dt LIBBSM 3 30.Os 31.Sh NAME 32.Nm libbsm 33.Nd "Basic Security Module (BSM) Audit API" 34.Sh LIBRARY 35.Lb libbsm 36.Sh SYNOPSIS 37.In bsm/libbsm.h 38.Sh DESCRIPTION 39The 40.Nm 41library routines provide an interface to BSM audit record streams, allowing 42both the parsing of existing audit streams, as well as the creation of new 43audit records and streams. 44.Sh INTERFACES 45The 46.Nm 47library 48provides a large number of Audit programming interfaces in several classes: 49event stream interfaces, class interfaces, control interfaces, event 50interfaces, I/O interfaces, mask interfaces, notification interfaces, token 51interfaces, and user interfaces. 52These are described respectively in the 53.Xr au_class 3 , 54.Xr au_control 3 , 55.Xr au_event 3 , 56.Xr au_mask 3 , 57.Xr au_notify 3 , 58.Xr au_stream 3 , 59.Xr au_token 3 , 60and 61.Xr au_user 3 62manual pages. 63.Ss Audit Event Stream Interfaces 64Audit event stream interfaces support interaction with file-backed audit 65event streams: 66.Xr au_close 3 , 67.Xr au_close_buffer 3 , 68.Xr au_free_token 3 , 69.Xr au_open 3 , 70.Xr au_write 3 , 71.Xr audit_submit 3 . 72.Ss Audit Class Interfaces 73Audit class interfaces support the look up of information from the 74.Xr audit_class 5 75database: 76.Xr endauclass 3 , 77.Xr getauclassent 3 , 78.Xr getauclassent_r 3 , 79.Xr getauclassnam 3 , 80.Xr getauclassnam_r 3 , 81.Xr setauclass 3 . 82.Ss Audit Control Interfaces 83Audit control interfaces support the look up of information from the 84.Xr audit_control 5 85database: 86.Xr endac 3 , 87.Xr setac 3 , 88.Xr getacdir 3 , 89.Xr getacfilesz 3 , 90.Xr getacflg 3 , 91.Xr getacmin 3 , 92.Xr getacna 3 , 93.Xr getacpol 3 , 94.Xr au_poltostr 3 , 95.Xr au_strtopol 3 . 96.Ss Audit Event Interfaces 97Audit event interfaces support the look up of information from the 98.Xr audit_event 5 99database: 100.Xr endauevent 3 , 101.Xr setauevent 3 , 102.Xr getauevent 3 , 103.Xr getauevent_r 3 , 104.Xr getauevnam 3 , 105.Xr getauevnam_r 3 , 106.Xr getauevnonam 3 , 107.Xr getauevnonam_r 3 , 108.Xr getauevnum 3 , 109.Xr getauevnum_r 3 . 110.Ss Audit I/O Interfaces 111Audit I/O interfaces support the processing and printing of tokens, as well 112as the reading of audit records: 113.Xr au_fetch_tok 3 , 114.Xr au_print_tok 3 , 115.Xr au_read_rec 3 . 116.Ss Audit Mask Interfaces 117Audit mask interfaces convert support the conversion between strings and 118.Vt au_mask_t 119values. 120They may also be used to determine if a particular audit event is matched 121by a mask: 122.Xr au_preselect 3 , 123.Xr getauditflagsbin 3 , 124.Xr getauditflagschar 3 . 125.Ss Audit Notification Interfaces 126Audit notification routines track audit state in a form permitting efficient 127update, avoiding frequent system calls to check the kernel audit state: 128.Xr au_get_state 3 , 129.Xr au_notify_initialize 3 , 130.Xr au_notify_terminate 3 . 131These interfaces are implemented only for Darwin/Mac OS X. 132.Ss Audit Token Interface 133Audit token interfaces permit the creation of tokens for use in creating 134audit records for submission to event streams. 135Each interface converts a C type to its 136.Vt token_t 137representation: 138.Xr au_to_arg 3 , 139.Xr au_to_arg32 3 , 140.Xr au_to_arg64 3 , 141.Xr au_to_attr64 3 , 142.Xr au_to_data 3 , 143.Xr au_to_exec_args 3 , 144.Xr au_to_exec_env 3 , 145.Xr au_to_exit 3 , 146.Xr au_to_file 3 , 147.Xr au_to_groups 3 , 148.Xr au_to_header32 3 , 149.Xr au_to_header64 3 , 150.Xr au_to_in_addr 3 , 151.Xr au_to_in_addr_ex 3 , 152.Xr au_to_ip 3 , 153.Xr au_to_ipc 3 , 154.Xr au_to_ipc_perm 3 , 155.Xr au_to_iport 3 , 156.Xr au_to_me 3 , 157.Xr au_to_newgroups 3 , 158.Xr au_to_opaque 3 , 159.Xr au_to_path 3 , 160.Xr au_to_process 3 , 161.Xr au_to_process32 3 , 162.Xr au_to_process64 3 , 163.Xr au_to_process_ex 3 , 164.Xr au_to_process32_ex 3 , 165.Xr au_to_process64_ex 3 , 166.Xr au_to_return 3 , 167.Xr au_to_return32 3 , 168.Xr au_to_return64 3 , 169.Xr au_to_seq 3 , 170.Xr au_to_sock_inet 3 , 171.Xr au_to_sock_inet32 3 , 172.Xr au_to_sock_inet128 3 , 173.Xr au_to_subject 3 , 174.Xr au_to_subject32 3 , 175.Xr au_to_subject64 3 , 176.Xr au_to_subject_ex 3 , 177.Xr au_to_subject32_ex 3 , 178.Xr au_to_subject64_ex 3 , 179.Xr au_to_text 3 , 180.Xr au_to_trailer 3 , 181.Xr au_to_zonename 3 . 182.Ss Audit User Interfaces 183Audit user interfaces support the look up of information from the 184.Xr audit_user 5 185database: 186.Xr au_user_mask 3 , 187.Xr endauuser 3 , 188.Xr setauuser 3 , 189.Xr getauuserent 3 , 190.Xr getauuserent_r 3 , 191.Xr getauusernam 3 , 192.Xr getauusernam_r 3 , 193.Xr getfauditflags 3 . 194.Sh SEE ALSO 195.Xr au_class 3 , 196.Xr audit_submit 3 , 197.Xr au_mask 3 , 198.Xr au_notify 3 , 199.Xr au_stream 3 , 200.Xr au_token 3 , 201.Xr au_user 3 , 202.Xr audit_class 5 , 203.Xr audit_control 5 204.Sh HISTORY 205The OpenBSM implementation was created by McAfee Research, the security 206division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. 207It was subsequently adopted by the TrustedBSD Project as the foundation for 208the OpenBSM distribution. 209.Sh AUTHORS 210.An -nosplit 211This software was created by 212.An Robert Watson , 213.An Wayne Salamon , 214and 215.An Suresh Krishnaswamy 216for McAfee Research, the security research division of McAfee, 217Inc., under contract to Apple Computer, Inc. 218.Pp 219The Basic Security Module (BSM) interface to audit records and audit event 220stream format were defined by Sun Microsystems. 221.Sh BUGS 222Bugs would not be unlikely. 223.Pp 224The 225.Nm 226library implementations are generally thread-safe, but not reentrant. 227.Pp 228The assignment of routines to classes could use some work, as it is 229decidely ad hoc. 230For example, 231.Fn au_read_rec 232should probably be considered a stream routine. 233