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#6 $ 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 bsm/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 52The 53.Fn au_preselect 54function 55calculates whether or not the audit event passed via 56.Fa event 57is matched by the audit mask passed via 58.Fa mask_p . 59The 60.Fa sorf 61argument indicates whether or not to consider the event as a success, 62if the 63.Dv AU_PRS_SUCCESS 64flag is set, or failure, if the 65.Dv AU_PRS_FAILURE 66flag is set. 67The 68.Fa flag 69argument accepts additional arguments influencing the behavior of 70.Fn au_preselect , 71including 72.Dv AU_PRS_REREAD , 73which causes the event to be re-looked up rather than read from the cache, 74or 75.Dv AU_PRS_USECACHE 76which forces use of the cache. 77.Pp 78The 79.Fn getauditflagsbin 80function 81converts a string representation of an audit mask passed via a character 82string pointed to by 83.Fa auditstr , 84returning the resulting mask, if valid, via 85.Fa *masks . 86.Pp 87The 88.Fn getauditflagschar 89function 90converts the audit event mask passed via 91.Fa *masks 92and converts it to a character string in a buffer pointed to by 93.Fa auditstr . 94See the 95.Sx BUGS 96section for more information on how to provide a buffer of 97sufficient size. 98If the 99.Fa verbose 100flag is set, the class description string retrieved from 101.Xr audit_class 5 102will be used; otherwise, the two-character class name. 103.Sh IMPLEMENTATION NOTES 104The 105.Fn au_preselect 106function 107makes implicit use of various audit database routines, and may influence 108the behavior of simultaneous or interleaved processing of those databases by 109other code. 110.Sh RETURN VALUES 111The 112.Fn au_preselect 113function 114returns 0 on success, or returns \-1 if there is a failure looking up the 115event type or other database access, in which case 116.Va errno 117will be set to indicate the error. 118It returns 1 if the event is matched; 0 if not. 119.Pp 120.Rv -std getauditflagsbin getauditflagschar 121.Sh SEE ALSO 122.Xr libbsm 3 , 123.Xr audit_class 5 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 AUTHORS 130.An -nosplit 131This software was created by 132.An Robert Watson , 133.An Wayne Salamon , 134and 135.An Suresh Krishnaswamy 136for McAfee Research, the security research division of McAfee, 137Inc., under contract to Apple Computer, Inc. 138.Pp 139The Basic Security Module (BSM) interface to audit records and audit event 140stream format were defined by Sun Microsystems. 141.Sh BUGS 142The 143.Va errno 144variable 145may not always be properly set in the event of an error. 146.Pp 147The 148.Fn getauditflagschar 149function 150does not provide a way to indicate how long the character buffer is, in order 151to detect overflow. 152As a result, the caller must always provide a buffer of sufficient length for 153any possible mask, which may be calculated as three times the number of 154non-zero bits in the mask argument in the event non-verbose class names are 155used, and is not trivially predictable for verbose class names. 156This API should be replaced with a more robust one. 157