xref: /freebsd/contrib/openbsm/libbsm/au_io.3 (revision b3bc3d792546cd39d9ca6e4f670c4d3f8d2a42cf)
1ca0716f5SRobert Watson.\"-
2aa772005SRobert Watson.\" Copyright (c) 2009 Apple, Inc.
3ca0716f5SRobert Watson.\" Copyright (c) 2005 Robert N. M. Watson
4ca0716f5SRobert Watson.\" All rights reserved.
5ca0716f5SRobert Watson.\"
6ca0716f5SRobert Watson.\" Redistribution and use in source and binary forms, with or without
7ca0716f5SRobert Watson.\" modification, are permitted provided that the following conditions
8ca0716f5SRobert Watson.\" are met:
9ca0716f5SRobert Watson.\" 1. Redistributions of source code must retain the above copyright
10ca0716f5SRobert Watson.\"    notice, this list of conditions and the following disclaimer.
11ca0716f5SRobert Watson.\" 2. Redistributions in binary form must reproduce the above copyright
12ca0716f5SRobert Watson.\"    notice, this list of conditions and the following disclaimer in the
13ca0716f5SRobert Watson.\"    documentation and/or other materials provided with the distribution.
14ca0716f5SRobert Watson.\"
15ca0716f5SRobert Watson.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16ca0716f5SRobert Watson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17ca0716f5SRobert Watson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18ca0716f5SRobert Watson.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19ca0716f5SRobert Watson.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20ca0716f5SRobert Watson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21ca0716f5SRobert Watson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22ca0716f5SRobert Watson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23ca0716f5SRobert Watson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24ca0716f5SRobert Watson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25ca0716f5SRobert Watson.\" SUCH DAMAGE.
26ca0716f5SRobert Watson.\"
27*b3bc3d79SAlan Somers.Dd May 30, 2018
28ca0716f5SRobert Watson.Dt AU_IO 3
29ca0716f5SRobert Watson.Os
30ca0716f5SRobert Watson.Sh NAME
31ca0716f5SRobert Watson.Nm au_fetch_tok ,
32ca0716f5SRobert Watson.Nm au_print_tok ,
33aa772005SRobert Watson.Nm au_print_flags_tok ,
34ca0716f5SRobert Watson.Nm au_read_rec
35bc168a6cSRobert Watson.Nd "perform I/O involving an audit record"
36ca0716f5SRobert Watson.Sh LIBRARY
37ca0716f5SRobert Watson.Lb libbsm
38ca0716f5SRobert Watson.Sh SYNOPSIS
39bc168a6cSRobert Watson.In bsm/libbsm.h
40ca0716f5SRobert Watson.Ft int
41ca0716f5SRobert Watson.Fn au_fetch_tok "tokenstr_t *tok" "u_char *buf" "int len"
42ca0716f5SRobert Watson.Ft void
43bc168a6cSRobert Watson.Fo au_print_tok
44bc168a6cSRobert Watson.Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "char raw" "char sfrm"
45bc168a6cSRobert Watson.Fc
46aa772005SRobert Watson.Ft void
47aa772005SRobert Watson.Fo au_print_flags_tok
48aa772005SRobert Watson.Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "int oflags"
49aa772005SRobert Watson.Fc
50ca0716f5SRobert Watson.Ft int
51ca0716f5SRobert Watson.Fn au_read_rec "FILE *fp" "u_char **buf"
52ca0716f5SRobert Watson.Sh DESCRIPTION
53ca0716f5SRobert WatsonThese interfaces support input and output (I/O) involving audit records,
54ca0716f5SRobert Watsoninternalizing an audit record from a byte stream, converting a token to
55ca0716f5SRobert Watsoneither a raw or default string, and reading a single record from a file.
56ca0716f5SRobert Watson.Pp
57bc168a6cSRobert WatsonThe
58ca0716f5SRobert Watson.Fn au_fetch_tok
59bc168a6cSRobert Watsonfunction
60ca0716f5SRobert Watsonreads a token from the passed buffer
61bc168a6cSRobert Watson.Fa buf
62ca0716f5SRobert Watsonof length
63bc168a6cSRobert Watson.Fa len
64ca0716f5SRobert Watsonbytes, and returns a pointer to the token via
65bc168a6cSRobert Watson.Fa tok .
66ca0716f5SRobert Watson.Pp
67bc168a6cSRobert WatsonThe
68ca0716f5SRobert Watson.Fn au_print_tok
69bc168a6cSRobert Watsonfunction
70ca0716f5SRobert Watsonprints a string form of the token
71bc168a6cSRobert Watson.Fa tok
72ca0716f5SRobert Watsonto the file output stream
73bc168a6cSRobert Watson.Fa outfp ,
74ca0716f5SRobert Watsoneither in default mode, or raw mode if
75bc168a6cSRobert Watson.Fa raw
76ca0716f5SRobert Watsonis set non-zero.
77ca0716f5SRobert WatsonThe delimiter
78bc168a6cSRobert Watson.Fa del
79ca0716f5SRobert Watsonis used when printing.
80aa772005SRobert WatsonThe
81aa772005SRobert Watson.Fn au_print_flags_tok
82aa772005SRobert Watsonfunction is a replacement for
83aa772005SRobert Watson.Fn au_print_tok .
84aa772005SRobert WatsonThe
85aa772005SRobert Watson.Fa oflags
86aa772005SRobert Watsoncontrols how the output should be formatted and is specified by
87aa772005SRobert Watsonor'ing the following flags:
88aa772005SRobert Watson.Pp
89aa772005SRobert Watson.Bl -tag -width AU_OFLAG_NORESOLVE -compact -offset indent
90aa772005SRobert Watson.It Li AU_OFLAG_NONE
91aa772005SRobert WatsonUse the default form.
92aa772005SRobert Watson.It Li AU_OFLAG_NORESOLVE
93aa772005SRobert WatsonLeave user and group IDs in their numeric form.
94aa772005SRobert Watson.It Li AU_OFLAG_RAW
95aa772005SRobert WatsonUse the raw, numeric form.
96aa772005SRobert Watson.It Li AU_OFLAG_SHORT
97aa772005SRobert WatsonUse the short form.
98aa772005SRobert Watson.It Li AU_OFLAG_XML
99aa772005SRobert WatsonUse the XML form.
100aa772005SRobert Watson.El
101aa772005SRobert Watson.Pp
102aa772005SRobert WatsonThe flags options AU_OFLAG_SHORT and AU_OFLAG_RAW are exclusive and
103aa772005SRobert Watsonshould not be used together.
104ca0716f5SRobert Watson.Pp
105bc168a6cSRobert WatsonThe
106ca0716f5SRobert Watson.Fn au_read_rec
107bc168a6cSRobert Watsonfunction
108ca0716f5SRobert Watsonreads an audit record from the file stream
109bc168a6cSRobert Watson.Fa fp ,
110ca0716f5SRobert Watsonand returns an allocated memory buffer containing the record via
111bc168a6cSRobert Watson.Fa *buf ,
112ca0716f5SRobert Watsonwhich must be freed by the caller using
113ca0716f5SRobert Watson.Xr free 3 .
114ca0716f5SRobert Watson.Pp
115ca0716f5SRobert WatsonA typical use of these routines might open a file with
116ca0716f5SRobert Watson.Xr fopen 3 ,
117ca0716f5SRobert Watsonthen read records from the file sequentially by calling
118ca0716f5SRobert Watson.Fn au_read_rec .
119ca0716f5SRobert WatsonEach record would be broken down into components tokens through sequential
120ca0716f5SRobert Watsoncalls to
121ca0716f5SRobert Watson.Fn au_fetch_tok
122ca0716f5SRobert Watsonon the buffer, and then invoking
123aa772005SRobert Watson.Fn au_print_flags_tok
124ca0716f5SRobert Watsonto print each token to an output stream such as
125ca0716f5SRobert Watson.Dv stdout .
126ca0716f5SRobert WatsonOn completion of the processing of each record, a call to
127ca0716f5SRobert Watson.Xr free 3
128ca0716f5SRobert Watsonwould be used to free the record buffer.
129ca0716f5SRobert WatsonFinally, the source stream would be closed by a call to
130ca0716f5SRobert Watson.Xr fclose 3 .
131ca0716f5SRobert Watson.Sh RETURN VALUES
132*b3bc3d79SAlan SomersOn success,
133ca0716f5SRobert Watson.Fn au_fetch_tok
134*b3bc3d79SAlan Somersreturns 0 while
135ca0716f5SRobert Watson.Fn au_read_rec
136*b3bc3d79SAlan Somersreturns the number of bytes read.
137*b3bc3d79SAlan SomersBoth functions return \-1 on failure with
138*b3bc3d79SAlan Somers.Va errno
139*b3bc3d79SAlan Somersset appropriately.
140ca0716f5SRobert Watson.Sh SEE ALSO
141ca0716f5SRobert Watson.Xr free 3 ,
142ca0716f5SRobert Watson.Xr libbsm 3
143ca0716f5SRobert Watson.Sh HISTORY
144ca0716f5SRobert WatsonThe OpenBSM implementation was created by McAfee Research, the security
145ca0716f5SRobert Watsondivision of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
146ca0716f5SRobert WatsonIt was subsequently adopted by the TrustedBSD Project as the foundation for
147ca0716f5SRobert Watsonthe OpenBSM distribution.
148aa772005SRobert Watson.Pp
149aa772005SRobert WatsonThe
150aa772005SRobert Watson.Fn au_print_flags_tok
151aa772005SRobert Watsonfunction was added by Stacey Son as a replacement for the
152aa772005SRobert Watson.Fn au_print_tok
153aa772005SRobert Watsonso new output formatting flags can be easily added without changing the API.
154aa772005SRobert WatsonThe
155aa772005SRobert Watson.Fn au_print_tok
156aa772005SRobert Watsonis obsolete but remains in the API to support legacy code.
157bc168a6cSRobert Watson.Sh AUTHORS
158bc168a6cSRobert Watson.An -nosplit
159bc168a6cSRobert WatsonThis software was created by
160bc168a6cSRobert Watson.An Robert Watson ,
161bc168a6cSRobert Watson.An Wayne Salamon ,
162bc168a6cSRobert Watsonand
163bc168a6cSRobert Watson.An Suresh Krishnaswamy
164bc168a6cSRobert Watsonfor McAfee Research, the security research division of McAfee,
165bc168a6cSRobert WatsonInc., under contract to Apple Computer, Inc.
166bc168a6cSRobert Watson.Pp
167bc168a6cSRobert WatsonThe Basic Security Module (BSM) interface to audit records and audit event
168bc168a6cSRobert Watsonstream format were defined by Sun Microsystems.
169ca0716f5SRobert Watson.Sh BUGS
170bc168a6cSRobert WatsonThe
171ca0716f5SRobert Watson.Va errno
172bc168a6cSRobert Watsonvariable
173ca0716f5SRobert Watsonmay not always be properly set in the event of an error.
174