1.\"- 2.\" Copyright (c) 2005 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_mask.3#3 $ 27.\" 28.Dd April 19, 2005 29.Dt AU_MASK 3 30.Os 31.Sh NAME 32.Nm au_preselect , 33.Nm getauditflagsbin , 34.Nm getauditflagschar 35.Nd "Convert between string and numeric values of audit masks" 36.Sh LIBRARY 37.Lb libbsm 38.Sh SYNOPSIS 39.In libbsm.h 40.Ft int 41.Fn au_preselect "au_event_t event" "au_mask_t *mask_p" "int sorf" "int flag" 42.Ft int 43.Fn getauditflagsbin "char *auditstr" "au_mask_t *masks" 44.Ft int 45.Fn getauditflagschar "char *auditstr" "au_mask_t *masks" "int verbose" 46.Sh DESCRIPTION 47These interfaces support processing of an audit mask represented by type 48.Vt au_mask_t , 49including conversion between numeric and text formats, and computing whether 50or not an event is matched by a mask. 51.Pp 52.Fn au_preselect 53calculates whether or not the audit event passed via 54.Va event 55is matched by the audit mask passed via 56.Va au_mask_t . 57The 58.Va sorf 59argument indicates whether or not to consider the event as a success, 60if the 61.Dv AU_PRS_SUCCESS 62flag is set, or failure, if the 63.Dv AU_PRS_FAILURE 64flag is set. 65The 66.Va flag 67argument accepts additional arguments influencing the behavior of 68.Fn au_preselect , 69including 70.Dv AU_PRS_REREAD , 71which causes the event to be re-looked up rather than read from the cache, 72or 73.Dv AU_PRS_USECACHE 74which forces use of the cache. 75.Pp 76.Fn getauditflagsbin 77converts a string representation of an audit mask passed via a character 78string pointed to by 79.Va auditstr , 80returning the resulting mask, if valid, via 81.Va *masks . 82.Pp 83.Fn getauditflagschar 84converts the audit event mask passed via 85.Va *masks 86and converts it to a character string in a buffer pointed to by 87.Va auditstr . 88See the BUGS section for more information on how to provide a buffer of 89sufficient size. 90If the 91.Va verbose 92flag is set, the class description string retrieved from 93.Xr audit_class 5 94will be used; otherwise, the two-character class name. 95.Sh RETURN VALUES 96.Fn au_preselect 97returns 0 on success, or returns -1 if there is a failure looking up the 98event type or other database access, in which case 99.Va errno 100will be set to indicate the error. 101It returns 1 if the event is matched; 0 if not. 102.Pp 103.Fn getauditflagsbin 104and 105.Fn getauditflagschar 106returns 0 on success, or -1 if there is a failure, in which case 107.Va errno 108will be set to indicate the error. 109.Sh IMPLEMENTATION NOTES 110.Fn au_preselect 111makes implicit use of various audit database routines, and may influence 112the behavior of simultaneous or interleaved processing of those databases by 113other code. 114.Sh SEE ALSO 115.Xr libbsm 3 , 116.Xr audit_class 5 117.Sh AUTHORS 118This software was created by Robert Watson, Wayne Salamon, and Suresh 119Krishnaswamy for McAfee Research, the security research division of McAfee, 120Inc., under contract to Apple Computer, Inc. 121.Pp 122The Basic Security Module (BSM) interface to audit records and audit event 123stream format were defined by Sun Microsystems. 124.Sh HISTORY 125The OpenBSM implementation was created by McAfee Research, the security 126division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. 127It was subsequently adopted by the TrustedBSD Project as the foundation for 128the OpenBSM distribution. 129.Sh BUGS 130.Va errno 131may not always be properly set in the event of an error. 132.Pp 133.Fn getauditflagschar 134does not provide a way to indicate how long the character buffer is, in order 135to detect overflow. 136As a result, the caller must always provide a buffer of sufficient length for 137any possible mask, which may be calculated as three times the number of 138non-zero bits in the mask argument in the event non-verbose class names are 139used, and is not trivially predictable for verbose class names. 140This API should be replaced with a more robust one. 141