contrib/openbsm/libbsm/au_mask.3

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