155 lines
4.9 KiB
Groff
155 lines
4.9 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.
|
|
.\"
|
|
.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 bsm/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
|
|
The
|
|
.Fn au_preselect
|
|
function
|
|
calculates whether or not the audit event passed via
|
|
.Fa event
|
|
is matched by the audit mask passed via
|
|
.Fa mask_p .
|
|
The
|
|
.Fa 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
|
|
.Fa 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
|
|
The
|
|
.Fn getauditflagsbin
|
|
function
|
|
converts a string representation of an audit mask passed via a character
|
|
string pointed to by
|
|
.Fa auditstr ,
|
|
returning the resulting mask, if valid, via
|
|
.Fa *masks .
|
|
.Pp
|
|
The
|
|
.Fn getauditflagschar
|
|
function
|
|
converts the audit event mask passed via
|
|
.Fa *masks
|
|
and converts it to a character string in a buffer pointed to by
|
|
.Fa auditstr .
|
|
See the
|
|
.Sx BUGS
|
|
section for more information on how to provide a buffer of
|
|
sufficient size.
|
|
If the
|
|
.Fa verbose
|
|
flag is set, the class description string retrieved from
|
|
.Xr audit_class 5
|
|
will be used; otherwise, the two-character class name.
|
|
.Sh IMPLEMENTATION NOTES
|
|
The
|
|
.Fn au_preselect
|
|
function
|
|
makes implicit use of various audit database routines, and may influence
|
|
the behavior of simultaneous or interleaved processing of those databases by
|
|
other code.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn au_preselect
|
|
function
|
|
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
|
|
.Rv -std getauditflagsbin getauditflagschar
|
|
.Sh SEE ALSO
|
|
.Xr libbsm 3 ,
|
|
.Xr audit_class 5
|
|
.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
|
|
The
|
|
.Va errno
|
|
variable
|
|
may not always be properly set in the event of an error.
|
|
.Pp
|
|
The
|
|
.Fn getauditflagschar
|
|
function
|
|
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.
|