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