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.Dd April 19, 2005 27.Dt AU_MASK 3 28.Os 29.Sh NAME 30.Nm au_preselect , 31.Nm getauditflagsbin , 32.Nm getauditflagschar 33.Nd "convert between string and numeric values of audit masks" 34.Sh LIBRARY 35.Lb libbsm 36.Sh SYNOPSIS 37.In bsm/libbsm.h 38.Ft int 39.Fn au_preselect "au_event_t event" "au_mask_t *mask_p" "int sorf" "int flag" 40.Ft int 41.Fn getauditflagsbin "char *auditstr" "au_mask_t *masks" 42.Ft int 43.Fn getauditflagschar "char *auditstr" "au_mask_t *masks" "int verbose" 44.Sh DESCRIPTION 45These interfaces support processing of an audit mask represented by type 46.Vt au_mask_t , 47including conversion between numeric and text formats, and computing whether 48or not an event is matched by a mask. 49.Pp 50The 51.Fn au_preselect 52function 53calculates whether or not the audit event passed via 54.Fa event 55is matched by the audit mask passed via 56.Fa mask_p . 57The 58.Fa 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.Fa 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 76The 77.Fn getauditflagsbin 78function 79converts a string representation of an audit mask passed via a character 80string pointed to by 81.Fa auditstr , 82returning the resulting mask, if valid, via 83.Fa *masks . 84.Pp 85The 86.Fn getauditflagschar 87function 88converts the audit event mask passed via 89.Fa *masks 90and converts it to a character string in a buffer pointed to by 91.Fa auditstr . 92See the 93.Sx BUGS 94section for more information on how to provide a buffer of 95sufficient size. 96If the 97.Fa verbose 98flag is set, the class description string retrieved from 99.Xr audit_class 5 100will be used; otherwise, the two-character class name. 101.Sh IMPLEMENTATION NOTES 102The 103.Fn au_preselect 104function 105makes implicit use of various audit database routines, and may influence 106the behavior of simultaneous or interleaved processing of those databases by 107other code. 108.Sh RETURN VALUES 109The 110.Fn au_preselect 111function 112returns 0 on success, or returns \-1 if there is a failure looking up the 113event type or other database access, in which case 114.Va errno 115will be set to indicate the error. 116It returns 1 if the event is matched; 0 if not. 117.Pp 118.Rv -std getauditflagsbin getauditflagschar 119.Sh SEE ALSO 120.Xr libbsm 3 , 121.Xr audit_class 5 122.Sh HISTORY 123The OpenBSM implementation was created by McAfee Research, the security 124division of McAfee Inc., under contract to Apple Computer, Inc., in 2004. 125It was subsequently adopted by the TrustedBSD Project as the foundation for 126the OpenBSM distribution. 127.Sh AUTHORS 128.An -nosplit 129This software was created by 130.An Robert Watson , 131.An Wayne Salamon , 132and 133.An Suresh Krishnaswamy 134for McAfee Research, the security research division of McAfee, 135Inc., under contract to Apple Computer, Inc. 136.Pp 137The Basic Security Module (BSM) interface to audit records and audit event 138stream format were defined by Sun Microsystems. 139.Sh BUGS 140The 141.Va errno 142variable 143may not always be properly set in the event of an error. 144.Pp 145The 146.Fn getauditflagschar 147function 148does not provide a way to indicate how long the character buffer is, in order 149to detect overflow. 150As a result, the caller must always provide a buffer of sufficient length for 151any possible mask, which may be calculated as three times the number of 152non-zero bits in the mask argument in the event non-verbose class names are 153used, and is not trivially predictable for verbose class names. 154This API should be replaced with a more robust one. 155