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