diff options
Diffstat (limited to 'contrib/openbsm/libbsm/au_mask.3')
-rw-r--r-- | contrib/openbsm/libbsm/au_mask.3 | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/contrib/openbsm/libbsm/au_mask.3 b/contrib/openbsm/libbsm/au_mask.3 new file mode 100644 index 0000000..67bb187 --- /dev/null +++ b/contrib/openbsm/libbsm/au_mask.3 @@ -0,0 +1,140 @@ +.\"- +.\" 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. |