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