freebsd-skq/contrib/openbsm/libbsm/au_mask.3

.\"-
.\" 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#3 $
.\"
.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 simultaneous 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.