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