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