1.\"- 2.\" Copyright (c) 2005 Robert N. M. Watson 3.\" Copyright (c) 2008 Apple Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd March 14, 2018 28.Dt GETAUDIT 2 29.Os 30.Sh NAME 31.Nm getaudit , 32.Nm getaudit_addr 33.Nd "retrieve audit session state" 34.Sh SYNOPSIS 35.In bsm/audit.h 36.Ft int 37.Fn getaudit "auditinfo_t *auditinfo" 38.Ft int 39.Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length" 40.Sh DESCRIPTION 41The 42.Fn getaudit 43system call 44retrieves the active audit session state for the current process via the 45.Vt auditinfo_t 46pointed to by 47.Fa auditinfo . 48The 49.Fn getaudit_addr 50system call 51retrieves extended state via 52.Fa auditinfo_addr 53and 54.Fa length . 55.Pp 56The 57.Fa auditinfo_t 58data structure is defined as follows: 59.Bd -literal -offset indent 60struct auditinfo { 61 au_id_t ai_auid; /* Audit user ID */ 62 au_mask_t ai_mask; /* Audit masks */ 63 au_tid_t ai_termid; /* Terminal ID */ 64 au_asid_t ai_asid; /* Audit session ID */ 65 au_asflgs_t ai_flags; /* Audit session flags. */ 66}; 67typedef struct auditinfo auditinfo_t; 68.Ed 69.Pp 70The 71.Fa ai_auid 72variable contains the audit identifier which is recorded in the audit log for 73each event the process caused. 74.Pp 75The 76.Fa au_mask_t 77data structure defines the bit mask for auditing successful and failed events 78out of the predefined list of event classes. 79It is defined as follows: 80.Bd -literal -offset indent 81struct au_mask { 82 unsigned int am_success; /* success bits */ 83 unsigned int am_failure; /* failure bits */ 84}; 85typedef struct au_mask au_mask_t; 86.Ed 87.Pp 88The 89.Fa au_termid_t 90data structure defines the Terminal ID recorded with every event caused by the 91process. 92It is defined as follows: 93.Bd -literal -offset indent 94struct au_tid { 95 dev_t port; 96 u_int32_t machine; 97}; 98typedef struct au_tid au_tid_t; 99.Ed 100.Pp 101The 102.Fa ai_asid 103variable contains the audit session ID which is recorded with every event 104caused by the process. 105.Pp 106The 107.Fn getaudit_addr 108system call 109uses the expanded 110.Fa auditinfo_addr_t 111data structure and supports Terminal IDs with larger addresses 112such as those used in IP version 6. 113It is defined as follows: 114.Bd -literal -offset indent 115struct auditinfo_addr { 116 au_id_t ai_auid; /* Audit user ID. */ 117 au_mask_t ai_mask; /* Audit masks. */ 118 au_tid_addr_t ai_termid; /* Terminal ID. */ 119 au_asid_t ai_asid; /* Audit session ID. */ 120}; 121typedef struct auditinfo_addr auditinfo_addr_t; 122.Ed 123.Pp 124The 125.Fa au_tid_addr_t 126data structure which includes a larger address storage field and an additional 127field with the type of address stored: 128.Bd -literal -offset indent 129struct au_tid_addr { 130 dev_t at_port; 131 u_int32_t at_type; 132 u_int32_t at_addr[4]; 133}; 134typedef struct au_tid_addr au_tid_addr_t; 135.Ed 136.Pp 137These system calls require an appropriate privilege to complete. 138.Sh RETURN VALUES 139.Rv -std getaudit getaudit_addr 140.Sh ERRORS 141The 142.Fn getaudit 143function will fail if: 144.Bl -tag -width Er 145.It Bq Er EFAULT 146A failure occurred while data transferred to or from 147the kernel failed. 148.It Bq Er EINVAL 149Illegal argument was passed by a system call. 150.It Bq Er EPERM 151The process does not have sufficient permission to complete 152the operation. 153.It Bq Er EOVERFLOW 154The 155.Fa length 156argument indicates an overflow condition will occur. 157.It Bq Er E2BIG 158The address is too big and, therefore, 159.Fn getaudit_addr 160should be used instead. 161.El 162.Sh SEE ALSO 163.Xr audit 2 , 164.Xr auditon 2 , 165.Xr getauid 2 , 166.Xr setaudit 2 , 167.Xr setauid 2 , 168.Xr libbsm 3 169.Sh HISTORY 170The OpenBSM implementation was created by McAfee Research, the security 171division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 172It was subsequently adopted by the TrustedBSD Project as the foundation for 173the OpenBSM distribution. 174.Sh AUTHORS 175.An -nosplit 176This software was created by McAfee Research, the security research division 177of McAfee, Inc., under contract to Apple Computer Inc. 178Additional authors include 179.An Wayne Salamon , 180.An Robert Watson , 181and SPARTA Inc. 182.Pp 183The Basic Security Module (BSM) interface to audit records and audit event 184stream format were defined by Sun Microsystems. 185.Pp 186This manual page was written by 187.An Robert Watson Aq rwatson@FreeBSD.org . 188