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