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