2 .\" Copyright (c) 2006 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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
35 .Nd "create and commit audit records"
43 .Fn au_write "int d" "token_t *tok"
45 .Fn au_close "int d" "int keep" "short event"
47 .Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen"
49 .Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen"
51 These interfaces allow applications to allocate audit records, construct a
52 record using a series of tokens, and commit the audit record to the system
54 An extension API is also provided to commit the record to an in-memory
55 buffer rather than the system audit log.
59 interface allocates a new audit record descriptor.
63 interface adds a token to an allocated audit descriptor.
64 When a token has been successfully added to a record, the caller no longer
65 owns the token memory, and does not need to free it directly via a call to
70 function is used to commit an audit record to the system audit log, or
72 In either cases, all resources associated with the record will be released.
75 argument determines the behavior: a value of
77 causes the record to be committed; a value of
79 causes it to be abandoned.
80 When the audit record is committed, a BSM header will be inserted before
81 tokens added to the record, using the event identifier passed via
83 and a trailer added to the end.
84 Committing a record to the system audit log requires privilege.
88 function writes the resulting record to an in-memory buffer of size
90 it will write back the filled buffer length into the same variable.
93 is the event identifier to use in the record header.
97 function generates the BSM stream output for a single token,
101 The initial buffer size and resulting data size are passed via
106 will free the token before returning.
110 returns a non-negative audit record descriptor number on success, or a
111 negative value on failure, along with error information in
117 .Fn au_close_buffer ,
120 return 0 on success, or a negative value on failure, along with error
127 The OpenBSM implementation was created by McAfee Research, the security
128 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
129 It was subsequently adopted by the TrustedBSD Project as the foundation for
130 the OpenBSM distribution.
133 This software was created by
137 .An Suresh Krishnaswamy
138 for McAfee Research, the security research division of McAfee,
139 Inc., under contract to Apple Computer, Inc.
141 The Basic Security Module (BSM) interface to audit records and audit event
142 stream format were defined by Sun Microsystems.
146 does not reserve kernel resources necessary to commit the record to the
147 trail; on systems supporting
149 the call will block until resources are available to commit the record.
150 However, this leads to the possibility of an action being permitted without
151 the record being guaranteed to go to disk.
154 would reserve resources necessary to commit any submitted record, releasing