2 .\" Copyright (c) 2005-2007 Robert N. M. Watson
3 .\" Copyright (c) 2008-2009 Apple Inc.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/libbsm.3#17 $
34 .Nd "Basic Security Module (BSM) Audit API"
42 library routines provide an interface to BSM audit record streams, allowing
43 both the parsing of existing audit streams, as well as the creation of new
44 audit records and streams.
49 provides a large number of Audit programming interfaces in several classes:
50 event stream interfaces, class interfaces, control interfaces, event
51 interfaces, I/O interfaces, mask interfaces, notification interfaces, token
52 interfaces, and user interfaces.
53 These are described respectively in the
64 .Ss Audit Event Stream Interfaces
65 Audit event stream interfaces support interaction with file-backed audit
68 .Xr au_close_buffer 3 ,
73 .Ss Audit Class Interfaces
74 Audit class interfaces support the look up of information from the
79 .Xr getauclassent_r 3 ,
81 .Xr getauclassnam_r 3 ,
83 .Ss Audit Control Interfaces
84 Audit control interfaces support the look up of information from the
97 .Ss Audit Event Interfaces
98 Audit event interfaces support the look up of information from the
108 .Xr getauevnonam_r 3 ,
111 .Ss Audit I/O Interfaces
112 Audit I/O interfaces support the processing and printing of tokens, as well
113 as the reading of audit records:
117 .Ss Audit Mask Interfaces
118 Audit mask interfaces convert support the conversion between strings and
121 They may also be used to determine if a particular audit event is matched
124 .Xr getauditflagsbin 3 ,
125 .Xr getauditflagschar 3 .
126 .Ss Audit Notification Interfaces
127 Audit notification routines track audit state in a form permitting efficient
128 update, avoiding frequent system calls to check the kernel audit state:
130 .Xr au_notify_initialize 3 ,
131 .Xr au_notify_terminate 3 .
132 These interfaces are implemented only for Darwin/Mac OS X.
133 .Ss Audit Token Interface
134 Audit token interfaces permit the creation of tokens for use in creating
135 audit records for submission to event streams.
136 Each interface converts a C type to its
144 .Xr au_to_exec_args 3 ,
145 .Xr au_to_exec_env 3 ,
149 .Xr au_to_header32 3 ,
150 .Xr au_to_header64 3 ,
151 .Xr au_to_in_addr 3 ,
152 .Xr au_to_in_addr_ex 3 ,
155 .Xr au_to_ipc_perm 3 ,
158 .Xr au_to_newgroups 3 ,
161 .Xr au_to_process 3 ,
162 .Xr au_to_process32 3 ,
163 .Xr au_to_process64 3 ,
164 .Xr au_to_process_ex 3 ,
165 .Xr au_to_process32_ex 3 ,
166 .Xr au_to_process64_ex 3 ,
168 .Xr au_to_return32 3 ,
169 .Xr au_to_return64 3 ,
171 .Xr au_to_sock_inet 3 ,
172 .Xr au_to_sock_inet32 3 ,
173 .Xr au_to_sock_inet128 3 ,
174 .Xr au_to_socket_ex 3 ,
175 .Xr au_to_subject 3 ,
176 .Xr au_to_subject32 3 ,
177 .Xr au_to_subject64 3 ,
178 .Xr au_to_subject_ex 3 ,
179 .Xr au_to_subject32_ex 3 ,
180 .Xr au_to_subject64_ex 3 ,
182 .Xr au_to_trailer 3 ,
183 .Xr au_to_zonename 3 .
184 .Ss Audit User Interfaces
185 Audit user interfaces support the look up of information from the
192 .Xr getauuserent_r 3 ,
194 .Xr getauusernam_r 3 ,
195 .Xr getfauditflags 3 .
196 .Ss Audit Constant Conversion Interfaces
197 These functions convert between BSM and local constants, including the
199 number, socket type, and protocol famil spaces, and must be used to generate
200 and interpret BSM return and extended socket tokens:
201 .Xr au_bsm_to_domain 3 ,
202 .Xr au_bsm_to_errno 3 ,
203 .Xr au_bsm_to_fcntl_cmd 3 ,
204 .Xr au_bsm_to_socket_type 3 ,
205 .Xr au_domain_to_bsm 3 ,
206 .Xr au_errno_to_bsm 3 ,
207 .Xr au_fcntl_cmd_to_bsm 3 ,
208 .Xr au_socket_type_to_bsm 3 .
215 .Xr au_socket_type 3 ,
223 The OpenBSM implementation was created by McAfee Research, the security
224 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
225 It was subsequently adopted by the TrustedBSD Project as the foundation for
226 the OpenBSM distribution.
229 This software was created by
233 .An Suresh Krishnaswamy
234 for McAfee Research, the security research division of McAfee,
235 Inc., under contract to Apple Computer, Inc.
237 The Basic Security Module (BSM) interface to audit records and audit event
238 stream format were defined by Sun Microsystems.
240 Bugs would not be unlikely.
244 library implementations are generally thread-safe, but not reentrant.
246 The assignment of routines to classes could use some work, as it is
250 should probably be considered a stream routine.