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