contrib/openbsm/libbsm/au_control.3

   1 .\"-
   2 .\" Copyright (c) 2005-2006 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_control.3#17 $
  27 .\"
  28 .Dd April 19, 2005
  29 .Dt AU_CONTROL 3
  30 .Os
  31 .Sh NAME
  32 .Nm setac ,
  33 .Nm endac ,
  34 .Nm getacdir ,
  35 .Nm getacdist ,
  36 .Nm getacexpire ,
  37 .Nm getacfilesz ,
  38 .Nm getacflg ,
  39 .Nm getachost ,
  40 .Nm getacmin ,
  41 .Nm getacna ,
  42 .Nm getacpol ,
  43 .Nm au_poltostr ,
  44 .Nm au_strtopol
  45 .Nd "look up information from the audit_control database"
  46 .Sh LIBRARY
  47 .Lb libbsm
  48 .Sh SYNOPSIS
  49 .In bsm/libbsm.h
  50 .Ft void
  51 .Fn setac void
  52 .Ft void
  53 .Fn endac void
  54 .Ft int
  55 .Fn getacdir "char *name" "int len"
  56 .Ft int
  57 .Fn getacdist "void"
  58 .Ft int
  59 .Fn getacexpire "int *andflg, time_t *age, size_t *size"
  60 .Ft int
  61 .Fn getacfilesz "size_t *size_val"
  62 .Ft int
  63 .Fn getacflg "char *auditstr" "int len"
  64 .Ft int
  65 .Fn getachost "char *auditstr" "int len"
  66 .Ft int
  67 .Fn getacmin "int *min_val"
  68 .Ft int
  69 .Fn getacna "char *auditstr" "int len"
  70 .Ft int
  71 .Fn getacpol "char *auditstr" "size_t len"
  72 .Ft ssize_t
  73 .Fn au_poltostr "int policy" "size_t maxsize" "char *buf"
  74 .Ft int
  75 .Fn au_strtopol "const char *polstr" "int *policy"
  76 .Sh DESCRIPTION
  77 These interfaces may be used to look up information from the
  78 .Xr audit_control 5
  79 database, which contains various audit-related administrative parameters.
  80 .Pp
  81 The
  82 .Fn setac
  83 function
  84 resets the database iterator to the beginning of the database; see the
  85 .Sx BUGS
  86 section for more information.
  87 .Pp
  88 The
  89 .Fn endac
  90 function
  91 closes the
  92 .Xr audit_control 5
  93 database.
  94 .Pp
  95 The
  96 .Fn getacdir
  97 function
  98 returns the name of the directory where log data is stored via the passed
  99 character buffer
 100 .Fa name
 101 of length
 102 .Fa len .
 103 .Pp
 104 The
 105 .Fn getacdist
 106 function returns a value that allows to decide if trail files distribution is
 107 turned on or off.
 108 .Pp
 109 The
 110 .Fn getacexpire
 111 function
 112 returns the audit trail file expiration parameters in the passed
 113 .Vt int
 114 buffer
 115 .Fa andflg ,
 116 .Vt time_t
 117 buffer
 118 .Fa age
 119 and
 120 .Vt size_t
 121 buffer
 122 .Fa size .
 123 If the parameter is not specified in the
 124 .Xr audit_control 5
 125 file it is set to zero.
 126 .Pp
 127 The
 128 .Fn getacfilesz
 129 function
 130 returns the audit trail rotation size in the passed
 131 .Vt size_t
 132 buffer
 133 .Fa size_val .
 134 .Pp
 135 The
 136 .Fn getacflg
 137 function
 138 returns the audit system flags via the the passed character buffer
 139 .Fa auditstr
 140 of length
 141 .Fa len .
 142 .Pp
 143 The
 144 .Fn getachost
 145 function
 146 returns the local systems's audit host information via the the passed character
 147 buffer
 148 .Fa auditstr
 149 of length
 150 .Fa len .
 151 .Pp
 152 The
 153 .Fn getacmin
 154 function
 155 returns the minimum free disk space for the audit log target file system via
 156 the passed
 157 .Fa min_val
 158 variable.
 159 .Pp
 160 The
 161 .Fn getacna
 162 function
 163 returns the non-attributable flags via the passed character buffer
 164 .Fa auditstr
 165 of length
 166 .Fa len .
 167 .Pp
 168 The
 169 .Fn getacpol
 170 function
 171 returns the audit policy flags via the passed character buffer
 172 .Fa auditstr
 173 of length
 174 .Fa len .
 175 .Pp
 176 The
 177 .Fn au_poltostr
 178 function
 179 converts a numeric audit policy mask,
 180 .Fa policy ,
 181 to a string in the passed character buffer
 182 .Fa buf
 183 of lenth
 184 .Fa maxsize .
 185 .Pp
 186 The
 187 .Fn au_strtopol
 188 function
 189 converts an audit policy flags string,
 190 .Fa polstr ,
 191 to a numeric audit policy mask returned via
 192 .Fa policy .
 193 .Sh RETURN VALULES
 194 The
 195 .Fn getacfilesz ,
 196 .Fn getacdir ,
 197 .Fn getacexpire ,
 198 .Fn getacflg ,
 199 .Fn getachost ,
 200 .Fn getacmin ,
 201 .Fn getacna ,
 202 .Fn getacpol ,
 203 and
 204 .Fn au_strtopol
 205 functions
 206 return 0 on success, or a negative value on failure, along with error
 207 information in
 208 .Va errno .
 209 .Pp
 210 The
 211 .Fn au_poltostr
 212 function
 213 returns a string length of 0 or more on success, or a negative value on
 214 if there is a failure.
 215 .Pp
 216 The
 217 .Fn getacdist
 218 function returns 1 if trail files distribution is turned on, 0 if it is turned
 219 off or negative value on failure.
 220 .Pp
 221 Functions that return a string value will return a failure if there is
 222 insufficient room in the passed character buffer for the full string.
 223 .Sh SEE ALSO
 224 .Xr libbsm 3 ,
 225 .Xr audit_control 5
 226 .Sh HISTORY
 227 The OpenBSM implementation was created by McAfee Research, the security
 228 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 229 It was subsequently adopted by the TrustedBSD Project as the foundation for
 230 the OpenBSM distribution.
 231 .Sh AUTHORS
 232 .An -nosplit
 233 This software was created by
 234 .An Robert Watson ,
 235 .An Wayne Salamon ,
 236 and
 237 .An Suresh Krishnaswamy
 238 for McAfee Research, the security research division of McAfee,
 239 Inc., under contract to Apple Computer, Inc.
 240 .Pp
 241 The Basic Security Module (BSM) interface to audit records and audit event
 242 stream format were defined by Sun Microsystems.
 243 .Sh BUGS
 244 These routines cannot currently distinguish between an entry not being found
 245 and an error accessing the database.
 246 The implementation should be changed to return an error via
 247 .Va errno
 248 when
 249 .Dv NULL
 250 is returned.
 251 .Pp
 252 There is no reason for the
 253 .Fn setac
 254 interface to be exposed as part of the public API, as it is called implicitly
 255 by other access functions and iteration is not supported.
 256 .Pp
 257 These interfaces inconsistently return various negative values depending on
 258 the failure mode, and do not always set
 259 .Va errno
 260 on failure.