3fdf6fa244
1.0 alpha 1, an implementation of the documented Sun Basic Security Module (BSM) Audit API and file format, as well as local extensions to support the Mac OS X and FreeBSD operating systems. Also included are command line tools for audit trail reduction and conversion to text, as well as documentation of the commands, file format, and APIs. This distribution is the foundation for the TrustedBSD Audit implementation, and is a pre-release. This is the first in a series of commits to introduce support for Common Criteria CAPP security event audit support. This software has been made possible through the generous contributions of Apple Computer, Inc., SPARTA, Inc., as well as members of the TrustedBSD Project, including Wayne Salamon <wsalamon> and Tom Rhodes <trhodes>. The original OpenBSM implementation was created by McAfee Research under contract to Apple Computer, Inc., as part of their CC CAPP security evaluation. Many thanks to: wsalamon, trhodes Obtained from: TrustedBSD Project
141 lines
5.0 KiB
Groff
141 lines
5.0 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2005 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_mask.3#2 $
|
|
.\"
|
|
.Dd April 19, 2005
|
|
.Dt AU_MASK 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm au_preselect ,
|
|
.Nm getauditflagsbin ,
|
|
.Nm getauditflagschar
|
|
.Nd "Convert between string and numeric values of audit masks"
|
|
.Sh LIBRARY
|
|
.Lb libbsm
|
|
.Sh SYNOPSIS
|
|
.In libbsm.h
|
|
.Ft int
|
|
.Fn au_preselect "au_event_t event" "au_mask_t *mask_p" "int sorf" "int flag"
|
|
.Ft int
|
|
.Fn getauditflagsbin "char *auditstr" "au_mask_t *masks"
|
|
.Ft int
|
|
.Fn getauditflagschar "char *auditstr" "au_mask_t *masks" "int verbose"
|
|
.Sh DESCRIPTION
|
|
These interfaces support processing of an audit mask represented by type
|
|
.Vt au_mask_t ,
|
|
including conversion between numeric and text formats, and computing whether
|
|
or not an event is matched by a mask.
|
|
.Pp
|
|
.Fn au_preselect
|
|
calculates whether or not the audit event passed via
|
|
.Va event
|
|
is matched by the audit mask passed via
|
|
.Va au_mask_t .
|
|
The
|
|
.Va sorf
|
|
argument indicates whether or not to consider the event as a success,
|
|
if the
|
|
.Dv AU_PRS_SUCCESS
|
|
flag is set, or failure, if the
|
|
.Dv AU_PRS_FAILURE
|
|
flag is set.
|
|
The
|
|
.Va flag
|
|
argument accepts additional arguments influencing the behavior of
|
|
.Fn au_preselect ,
|
|
including
|
|
.Dv AU_PRS_REREAD ,
|
|
which causes the event to be re-looked up rather than read from the cache,
|
|
or
|
|
.Dv AU_PRS_USECACHE
|
|
which forces use of the cache.
|
|
.Pp
|
|
.Fn getauditflagsbin
|
|
converts a string representation of an audit mask passed via a character
|
|
string pointed to by
|
|
.Va auditstr ,
|
|
returning the resulting mask, if valid, via
|
|
.Va *masks .
|
|
.Pp
|
|
.Fn getauditflagschar
|
|
converts the audit event mask passed via
|
|
.Va *masks
|
|
and converts it to a character string in a buffer pointed to by
|
|
.Va auditstr .
|
|
See the BUGS section for more information on how to provide a buffer of
|
|
sufficient size.
|
|
If the
|
|
.Va verbose
|
|
flag is set, the class description string retrieved from
|
|
.Xr audit_class 5
|
|
will be used; otherwise, the two-character class name.
|
|
.Sh RETURN VALUES
|
|
.Fn au_preselect
|
|
returns 0 on success, or returns -1 if there is a failure looking up the
|
|
event type or other database access, in which case
|
|
.Va errno
|
|
will be set to indicate the error.
|
|
It returns 1 if the event is matched; 0 if not.
|
|
.Pp
|
|
.Fn getauditflagsbin
|
|
and
|
|
.Fn getauditflagschar
|
|
returns 0 on success, or -1 if there is a failure, in which case
|
|
.Va errno
|
|
will be set to indicate the error.
|
|
.Sh IMPLEMENTATION NOTES
|
|
.Fn au_preselect
|
|
makes implicit use of various audit database routines, and may influence
|
|
the behavior of simultaenous or interleaved processing of those databases by
|
|
other code.
|
|
.Sh SEE ALSO
|
|
.Xr libbsm 3 ,
|
|
.Xr audit_class 5
|
|
.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
|
|
.Va errno
|
|
may not always be properly set in the event of an error.
|
|
.Pp
|
|
.Fn getauditflagschar
|
|
does not provide a way to indicate how long the character buffer is, in order
|
|
to detect overflow.
|
|
As a result, the caller must always provide a buffer of sufficient length for
|
|
any possible mask, which may be calculated as three times the number of
|
|
non-zero bits in the mask argument in the event non-verbose class names are
|
|
used, and is not trivially predictable for verbose class names.
|
|
This API should be replaced with a more robust one.
|