bb97b41819
notes since the last import: OpenBSM 1.0 alpha 11 - Reclassify certain read/write operations as having no class rather than the fr/fw class; our default classes audit intent (open) not operations (read, write). - Introduce AUE_SYSCTL_WRITE event so that BSD/Darwin systems can audit reads and writes of sysctls as separate events. Add additional kernel environment and jail events for FreeBSD. - Break AUDIT_TRIGGER_OPEN_NEW into two events, AUDIT_TRIGGER_ROTATE_USER (issued by the user audit(8) tool) and AUDIT_TRIGGER_ROTATE_KERNEL (issued by the kernel audit implementation) so that they can be distinguished. - Disable rate limiting of rotate requests; as the kernel doesn't retransmit a dropped request, the log file will otherwise grow indefinitely if the trigger is dropped. - Improve auditd debugging output. - Fix a number of threading related bugs in audit_control file reading routines. - Add APIs au_poltostr() and au_strtopol() to convert between text representations of audit_control policy flags and the flags passed to auditon(A_SETPOLICY) and retrieved from auditon(A_GETPOLICY). - Add API getacpol() to return the 'policy:' entry from audit_control, an extension to the Solaris file format to allow specification of policy persistent flags. - Update audump to print the audit_control policy field. - Update auditd to read the audit_control policy field and set the kernel policy to match it when configuring/reconfiguring. Remove the -s and -h arguments as these policies are now set via the configuration file. If a policy line is not found in the configuration file, continue with the current default of setting AUDIT_CNT. - Fix bugs in the parsing of large execve(2) arguments and environmental variable tokens; increase maximum parsed argument and variable count. - configure now detects strlcat(), used by policy-related functions. - Reference token and record sample files added to test tree. Obtained from: TrustedBSD Project
152 lines
5.0 KiB
Groff
152 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#5 $
|
|
.\"
|
|
.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 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 audit_submit 3 ,
|
|
.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 .
|