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