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