.\"-
.\" Copyright (c) 2006 Robert N. M. Watson
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd March 4, 2006
.Dt AU_OPEN 3
.Os
.Sh NAME
.Nm au_close ,
.Nm au_close_buffer ,
.Nm au_close_token ,
.Nm au_open ,
.Nm au_write
.Nd "create and commit audit records"
.Sh LIBRARY
.Lb libbsm
.Sh SYNOPSIS
.In bsm/libbsm.h
.Ft int
.Fn au_open void
.Ft int
.Fn au_write "int d" "token_t *tok"
.Ft int
.Fn au_close "int d" "int keep" "short event"
.Ft int
.Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen"
.Ft int
.Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen"
.Sh DESCRIPTION
These interfaces allow applications to allocate audit records, construct a
record using a series of tokens, and commit the audit record to the system
event log.
An extension API is also provided to commit the record to an in-memory
buffer rather than the system audit log.
.Pp
The
.Fn au_open
interface allocates a new audit record descriptor.
.Pp
The
.Fn au_write
interface adds a token to an allocated audit descriptor.
When a token has been successfully added to a record, the caller no longer
owns the token memory, and does not need to free it directly via a call to
.Xr au_free_token 3 .
.Pp
The
.Fn au_close
function is used to commit an audit record to the system audit log, or
abandon the record.
In either cases, all resources associated with the record will be released.
The
.Fa keep
argument determines the behavior: a value of
.Dv AU_TO_WRITE
causes the record to be committed; a value of
.Dv AU_TO_NO_WRITE
causes it to be abandoned.
When the audit record is committed, a BSM header will be inserted before
tokens added to the record, using the event identifier passed via
.Fa event ,
and a trailer added to the end.
Committing a record to the system audit log requires privilege.
.Pp
The
.Fn au_close_buffer
function writes the resulting record to an in-memory buffer of size
.Fa *buflen ;
it will write back the filled buffer length into the same variable.
The argument
.Fa event
is the event identifier to use in the record header.
.Pp
The
.Fn au_close_token
function generates the BSM stream output for a single token,
.Fa tok ,
in the passed buffer
.Fa buffer .
The initial buffer size and resulting data size are passed via
.Fa *buflen .
The
.Fn au_close_token
function
will free the token before returning.
.Sh RETURN VALUES
The function
.Fn au_open
returns a non-negative audit record descriptor number on success, or a
negative value on failure, along with error information in
.Va errno .
.Pp
The functions
.Fn au_write ,
.Fn au_close ,
.Fn au_close_buffer ,
and
.Fn au_close_token
return 0 on success, or a negative value on failure, along with error
information in
.Va errno .
.Sh SEE ALSO
.Xr audit_submit 3 ,
.Xr libbsm 3
.Sh HISTORY
The OpenBSM implementation was created by McAfee Research, the security
division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
It was subsequently adopted by the TrustedBSD Project as the foundation for
the OpenBSM distribution.
.Sh AUTHORS
.An -nosplit
This software was created by
.An Robert Watson ,
.An Wayne Salamon ,
and
.An Suresh Krishnaswamy
for McAfee Research, the security research division of McAfee,
Inc., under contract to Apple Computer, Inc.
.Pp
The Basic Security Module (BSM) interface to audit records and audit event
stream format were defined by Sun Microsystems.
.Sh BUGS
Currently,
.Fn au_open
does not reserve kernel resources necessary to commit the record to the
trail; on systems supporting
.Fn au_close ,
the call will block until resources are available to commit the record.
However, this leads to the possibility of an action being permitted without
the record being guaranteed to go to disk.
Ideally,
.Fn au_open
would reserve resources necessary to commit any submitted record, releasing
them on
.Fn au_close .