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 December 2, 2016
  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 int
  71 .Fn getacqsize "int *size_val"
  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 getacqsize
 178 function returns the size of the audit post-commit queue in the passed
 179 .Fa size_val
 180 buffer.
 181 If the parameter is not specified in the
 182 .Xr audit_control 5
 183 file it is set to
 184 .Dv -1 ,
 185 indicating that the kernel's default queue size is being used.
 186 .Pp
 187 The
 188 .Fn au_poltostr
 189 function
 190 converts a numeric audit policy mask,
 191 .Fa policy ,
 192 to a string in the passed character buffer
 193 .Fa buf
 194 of lenth
 195 .Fa maxsize .
 196 .Pp
 197 The
 198 .Fn au_strtopol
 199 function
 200 converts an audit policy flags string,
 201 .Fa polstr ,
 202 to a numeric audit policy mask returned via
 203 .Fa policy .
 204 .Sh RETURN VALUES
 205 The
 206 .Fn getacfilesz ,
 207 .Fn getacdir ,
 208 .Fn getacexpire ,
 209 .Fn getacflg ,
 210 .Fn getachost ,
 211 .Fn getacmin ,
 212 .Fn getacna ,
 213 .Fn getacpol ,
 214 .Fn getacqsize ,
 215 and
 216 .Fn au_strtopol
 217 functions
 218 return 0 on success, or a negative value on failure, along with error
 219 information in
 220 .Va errno .
 221 .Pp
 222 The
 223 .Fn au_poltostr
 224 function
 225 returns a string length of 0 or more on success, or a negative value on
 226 if there is a failure.
 227 .Pp
 228 The
 229 .Fn getacdist
 230 function returns 1 if trail files distribution is turned on, 0 if it is turned
 231 off or negative value on failure.
 232 .Pp
 233 Functions that return a string value will return a failure if there is
 234 insufficient room in the passed character buffer for the full string.
 235 .Sh SEE ALSO
 236 .Xr libbsm 3 ,
 237 .Xr audit_control 5
 238 .Sh HISTORY
 239 The OpenBSM implementation was created by McAfee Research, the security
 240 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 241 It was subsequently adopted by the TrustedBSD Project as the foundation for
 242 the OpenBSM distribution.
 243 .Sh AUTHORS
 244 .An -nosplit
 245 This software was created by
 246 .An Robert Watson ,
 247 .An Wayne Salamon ,
 248 and
 249 .An Suresh Krishnaswamy
 250 for McAfee Research, the security research division of McAfee,
 251 Inc., under contract to Apple Computer, Inc.
 252 .Pp
 253 The Basic Security Module (BSM) interface to audit records and audit event
 254 stream format were defined by Sun Microsystems.
 255 .Sh BUGS
 256 These routines cannot currently distinguish between an entry not being found
 257 and an error accessing the database.
 258 The implementation should be changed to return an error via
 259 .Va errno
 260 when
 261 .Dv NULL
 262 is returned.
 263 .Pp
 264 There is no reason for the
 265 .Fn setac
 266 interface to be exposed as part of the public API, as it is called implicitly
 267 by other access functions and iteration is not supported.
 268 .Pp
 269 These interfaces inconsistently return various negative values depending on
 270 the failure mode, and do not always set
 271 .Va errno
 272 on failure.