506764c6f6
- Use AU_TO_WRITE and AU_NO_TO_WRITE for the 'keep' argument to au_close(); previously we used hard-coded 0 and 1 values. - Add man page for au_open(), au_write(), au_close(), and au_close_buffer(). - Support a more complete range of data types for the arbitrary data token: add AUR_CHAR (alias to AUR_BYTE), remove AUR_LONG, add AUR_INT32 (alias to AUR_INT), add AUR_INT64. - Add au_close_token(), which allows writing a single token_t to a memory buffer. Not likely to be used much by applications, but useful for writing test tools. - Modify au_to_file() so that it accepts a timeval in user space, not just kernel -- this is not a Solaris BSM API so can be modified without causing compatibility issues. - Define a new API, au_to_header32_tm(), which adds a struct timeval argument to the ordinary au_to_header32(), which is now implemented by wrapping au_to_header32_tm() and calling gettimeofday(). #ifndef KERNEL the APIs that invoke gettimeofday(), rather than having a variable definition. Don't try to retrieve time zone information using gettimeofday(), as it's not needed, and introduces possible failure modes. - Don't perform byte order transformations on the addr/machine fields of the terminal ID that appears in the process32/subject32 tokens. These are assumed to be IP addresses, and as such, to be in network byte order. - Universally, APIs now assume that IP addresses and ports are provided in network byte order. APIs now generally provide these types in network byte order when decoding. - Beginnings of an OpenBSM test framework can now be found in openbsm/test. This code is not built or installed by default. - auditd now assigns more appropriate syslog levels to its debugging and error information. - Support for audit filters introduced: audit filters are dynamically loaded shared objects that run in the context of a new daemon, auditfilterd. The daemon reads from an audit pipe and feeds both BSM and parsed versions of records to shared objects using a module API. This will provide a framework for the writing of intrusion detection services. - New utility API, audit_submit(), added to capture common elements of audit record submission for many applications. Obtained from: TrustedBSD Project
150 lines
5.0 KiB
Groff
150 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.
|
|
.\"
|
|
.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_open.3#4 $
|
|
.\"
|
|
.Dd March 4, 2006
|
|
.Dt AU_OPEN 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm au_open ,
|
|
.Nm au_write ,
|
|
.Nm au_close ,
|
|
.Nm au_close_buffer
|
|
.Nd "Create and commit audit records"
|
|
.Sh LIBRARY
|
|
.Lb libbsm
|
|
.Sh SYNOPSIS
|
|
.In 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
|
|
.Va 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
|
|
.Va 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
|
|
.Va *buflen ;
|
|
it will write back the filled buffer length into the same variable.
|
|
The argument
|
|
.Va short
|
|
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,
|
|
.Va tok ,
|
|
in the passed buffer
|
|
.Va buffer .
|
|
The initial buffer size and resulting data size are passed via
|
|
.Va *buflen .
|
|
.Fn au_close_token
|
|
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 libbsm 3
|
|
.Sh AUTHORS
|
|
This software was created by Robert Watson, Wayne Salamon, and 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 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 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 .
|