xref: /freebsd/contrib/openbsm/libbsm/au_open.3 (revision 1f4bcc459a76b7aa664f3fd557684cd0ba6da352)
1.\"-
2.\" Copyright (c) 2006 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 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
24.\" SUCH DAMAGE.
25.\"
26.Dd March 4, 2006
27.Dt AU_OPEN 3
28.Os
29.Sh NAME
30.Nm au_close ,
31.Nm au_close_buffer ,
32.Nm au_close_token ,
33.Nm au_open ,
34.Nm au_write
35.Nd "create and commit audit records"
36.Sh LIBRARY
37.Lb libbsm
38.Sh SYNOPSIS
39.In bsm/libbsm.h
40.Ft int
41.Fn au_open void
42.Ft int
43.Fn au_write "int d" "token_t *tok"
44.Ft int
45.Fn au_close "int d" "int keep" "short event"
46.Ft int
47.Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen"
48.Ft int
49.Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen"
50.Sh DESCRIPTION
51These interfaces allow applications to allocate audit records, construct a
52record using a series of tokens, and commit the audit record to the system
53event log.
54An extension API is also provided to commit the record to an in-memory
55buffer rather than the system audit log.
56.Pp
57The
58.Fn au_open
59interface allocates a new audit record descriptor.
60.Pp
61The
62.Fn au_write
63interface adds a token to an allocated audit descriptor.
64When a token has been successfully added to a record, the caller no longer
65owns the token memory, and does not need to free it directly via a call to
66.Xr au_free_token 3 .
67.Pp
68The
69.Fn au_close
70function is used to commit an audit record to the system audit log, or
71abandon the record.
72In either cases, all resources associated with the record will be released.
73The
74.Fa keep
75argument determines the behavior: a value of
76.Dv AU_TO_WRITE
77causes the record to be committed; a value of
78.Dv AU_TO_NO_WRITE
79causes it to be abandoned.
80When the audit record is committed, a BSM header will be inserted before
81tokens added to the record, using the event identifier passed via
82.Fa event ,
83and a trailer added to the end.
84Committing a record to the system audit log requires privilege.
85.Pp
86The
87.Fn au_close_buffer
88function writes the resulting record to an in-memory buffer of size
89.Fa *buflen ;
90it will write back the filled buffer length into the same variable.
91The argument
92.Fa event
93is the event identifier to use in the record header.
94.Pp
95The
96.Fn au_close_token
97function generates the BSM stream output for a single token,
98.Fa tok ,
99in the passed buffer
100.Fa buffer .
101The initial buffer size and resulting data size are passed via
102.Fa *buflen .
103The
104.Fn au_close_token
105function
106will free the token before returning.
107.Sh RETURN VALUES
108The function
109.Fn au_open
110returns a non-negative audit record descriptor number on success, or a
111negative value on failure, along with error information in
112.Va errno .
113.Pp
114The functions
115.Fn au_write ,
116.Fn au_close ,
117.Fn au_close_buffer ,
118and
119.Fn au_close_token
120return 0 on success, or a negative value on failure, along with error
121information in
122.Va errno .
123.Sh SEE ALSO
124.Xr audit_submit 3 ,
125.Xr libbsm 3
126.Sh HISTORY
127The OpenBSM implementation was created by McAfee Research, the security
128division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
129It was subsequently adopted by the TrustedBSD Project as the foundation for
130the OpenBSM distribution.
131.Sh AUTHORS
132.An -nosplit
133This software was created by
134.An Robert Watson ,
135.An Wayne Salamon ,
136and
137.An Suresh Krishnaswamy
138for McAfee Research, the security research division of McAfee,
139Inc., under contract to Apple Computer, Inc.
140.Pp
141The Basic Security Module (BSM) interface to audit records and audit event
142stream format were defined by Sun Microsystems.
143.Sh BUGS
144Currently,
145.Fn au_open
146does not reserve kernel resources necessary to commit the record to the
147trail; on systems supporting
148.Fn au_close ,
149the call will block until resources are available to commit the record.
150However, this leads to the possibility of an action being permitted without
151the record being guaranteed to go to disk.
152Ideally,
153.Fn au_open
154would reserve resources necessary to commit any submitted record, releasing
155them on
156.Fn au_close .
157