157 lines
5.0 KiB
Groff
157 lines
5.0 KiB
Groff
.\"-
|
|
.\" 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 .
|