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.\" $P4: //depot/projects/trustedbsd/openbsm/man/getaudit.2#10 $ 28.\" 29.Dd October 19, 2008 30.Dt GETAUDIT 2 31.Os 32.Sh NAME 33.Nm getaudit , 34.Nm getaudit_addr 35.Nd "retrieve audit session state" 36.Sh SYNOPSIS 37.In bsm/audit.h 38.Ft int 39.Fn getaudit "auditinfo_t *auditinfo" 40.Ft int 41.Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length" 42.Sh DESCRIPTION 43The 44.Fn getaudit 45system call 46retrieves the active audit session state for the current process via the 47.Vt auditinfo_t 48pointed to by 49.Fa auditinfo . 50The 51.Fn getaudit_addr 52system call 53retrieves extended state via 54.Fa auditinfo_addr 55and 56.Fa length . 57.Pp 58The 59.Fa auditinfo_t 60data structure is defined as follows: 61.Bd -literal -offset indent 62struct auditinfo { 63 au_id_t ai_auid; /* Audit user ID */ 64 au_mask_t ai_mask; /* Audit masks */ 65 au_tid_t ai_termid; /* Terminal ID */ 66 au_asid_t ai_asid; /* Audit session ID */ 67}; 68typedef struct auditinfo auditinfo_t; 69.Ed 70.Pp 71The 72.Fa ai_auid 73variable contains the audit identifier which is recorded in the audit log for 74each event the process caused. 75.Pp 76The 77.Fa au_mask_t 78data structure defines the bit mask for auditing successful and failed events 79out of the predefined list of event classes. 80It is defined as follows: 81.Bd -literal -offset indent 82struct au_mask { 83 unsigned int am_success; /* success bits */ 84 unsigned int am_failure; /* failure bits */ 85}; 86typedef struct au_mask au_mask_t; 87.Ed 88.Pp 89The 90.Fa au_termid_t 91data structure defines the Terminal ID recorded with every event caused by the 92process. 93It is defined as follows: 94.Bd -literal -offset indent 95struct au_tid { 96 dev_t port; 97 u_int32_t machine; 98}; 99typedef struct au_tid au_tid_t; 100.Ed 101.Pp 102The 103.Fa ai_asid 104variable contains the audit session ID which is recorded with every event 105caused by the process. 106.Pp 107The 108.Fn getaudit_addr 109system call 110uses the expanded 111.Fa auditinfo_addr_t 112data structure and supports Terminal IDs with larger addresses 113such as those used in IP version 6. 114It is defined as follows: 115.Bd -literal -offset indent 116struct auditinfo_addr { 117 au_id_t ai_auid; /* Audit user ID. */ 118 au_mask_t ai_mask; /* Audit masks. */ 119 au_tid_addr_t ai_termid; /* Terminal ID. */ 120 au_asid_t ai_asid; /* Audit session ID. */ 121}; 122typedef struct auditinfo_addr auditinfo_addr_t; 123.Ed 124.Pp 125The 126.Fa au_tid_addr_t 127data structure which includes a larger address storage field and an additional 128field with the type of address stored: 129.Bd -literal -offset indent 130struct au_tid_addr { 131 dev_t at_port; 132 u_int32_t at_type; 133 u_int32_t at_addr[4]; 134}; 135typedef struct au_tid_addr au_tid_addr_t; 136.Ed 137.Pp 138These system calls require an appropriate privilege to complete. 139.Sh RETURN VALUES 140.Rv -std getaudit getaudit_addr 141.Sh ERRORS 142The 143.Fn getaudit 144function will fail if: 145.Bl -tag -width Er 146.It Bq Er EFAULT 147A failure occurred while data transferred to or from 148the kernel failed. 149.It Bq Er EINVAL 150Illegal argument was passed by a system call. 151.It Bq Er EPERM 152The process does not have sufficient permission to complete 153the operation. 154.It Bq Er EOVERFLOW 155The 156.Fa length 157argument indicates an overflow condition will occur. 158.It Bq Er E2BIG 159The address is too big and, therefore, 160.Fn getaudit_addr 161should be used instead. 162.El 163.Sh SEE ALSO 164.Xr audit 2 , 165.Xr auditon 2 , 166.Xr getauid 2 , 167.Xr setaudit 2 , 168.Xr setauid 2 , 169.Xr libbsm 3 170.Sh HISTORY 171The OpenBSM implementation was created by McAfee Research, the security 172division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 173It was subsequently adopted by the TrustedBSD Project as the foundation for 174the OpenBSM distribution. 175.Sh AUTHORS 176.An -nosplit 177This software was created by McAfee Research, the security research division 178of McAfee, Inc., under contract to Apple Computer Inc. 179Additional authors include 180.An Wayne Salamon , 181.An Robert Watson , 182and SPARTA Inc. 183.Pp 184The Basic Security Module (BSM) interface to audit records and audit event 185stream format were defined by Sun Microsystems. 186.Pp 187This manual page was written by 188.An Robert Watson Aq rwatson@FreeBSD.org . 189