1.\" 2.\" Copyright (c) 2008-2011 Apple Inc. All rights reserved. 3.\" 4.\" @APPLE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. Please obtain a copy of the License at 10.\" http://www.opensource.apple.com/apsl/ and read it before using this 11.\" file. 12.\" 13.\" The Original Code and all software distributed under the License are 14.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18.\" Please see the License for the specific language governing rights and 19.\" limitations under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.Dd March 4, 2011 24.Dt SETAUDIT_ADDR 2 25.Os 26.Sh NAME 27.Nm setaudit_addr , 28.Nm setaudit(NOW DEPRECATED) 29.Nd "set audit session state" 30.Sh SYNOPSIS 31.In bsm/audit.h 32.In bsm/audit_session.h 33.Ft int 34.Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length" 35.Sh SYNOPSIS (NOW DEPRECATED) 36.In bsm/audit.h 37.Ft int 38.Fn setaudit "auditinfo_t *auditinfo" 39.Sh DESCRIPTION 40The 41.Fn setaudit_addr 42system call 43uses the 44.Fa auditinfo_addr_t 45data structure for the 46.Fa auditinfo_addr 47argument which supports Terminal IDs with large addresses 48such as those used in IP version 6. It is defined as follows: 49.nf 50.Bd -literal -offset indent 51struct auditinfo_addr { 52 au_id_t ai_auid; /* Audit user ID. */ 53 au_mask_t ai_mask; /* Audit masks. */ 54 au_tid_addr_t ai_termid; /* Terminal ID. */ 55 au_asid_t ai_asid; /* Audit session ID. */ 56 u_int64_t ai_flags; /* Audit session flags */ 57}; 58typedef struct auditinfo_addr auditinfo_addr_t; 59.Ed 60.fi 61.Pp 62The 63.Fa ai_auid 64variable contains the audit identifier which is recorded in the audit log for 65each event the process caused. 66The value of AU_DEFAUDITID (-1) should not be used. 67The exception is if the value of audit identifier is known at the start 68of the session but will be determined and set later. 69Until 70.Fa ai_auid 71is set to something other than AU_DEFAUDITID any audit events 72generated by the system with be filtered by the non-attributed audit 73mask. 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.nf 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.fi 89.Pp 90The 91.Fa au_tid_addr_t 92data structure includes a larger address storage field and an additional 93field with the type of address stored: 94.nf 95.Bd -literal -offset indent 96struct au_tid_addr { 97 dev_t at_port; 98 u_int32_t at_type; 99 u_int32_t at_addr[4]; 100}; 101typedef struct au_tid_addr au_tid_addr_t; 102.Ed 103.fi 104.Pp 105The 106.Fa ai_asid 107variable contains the audit session ID which is recorded with every event 108caused by the process. 109It can be any value in the range 1 to PID_MAX (99999). 110If the value of AU_ASSIGN_ASID is used for 111.Fa ai_asid 112a unique session ID will be generated by the kernel. 113The audit session ID will be returned in the 114.Fa ai_asid 115field on success. 116.Pp 117The 118.Fa ai_flags 119field is opaque to the kernel and can be used to store flags associated 120with the audit session. 121Please see the 122.Ao Pa bsm/audit_session.h Ac 123header file 124for more information and flag definitions for this platform. 125.Pp 126The 127.Fa setaudit_addr 128system call require an appropriate privilege to complete. 129.Pp 130This system call should only be called once at the start of a new 131session and not again during the same session to update the session 132information. 133There are some exceptions, however. 134The 135.Fa ai_auid 136field may be updated later if initially set to the value of 137AU_DEFAUDITID (-1). 138Likewise, the 139.Fa ai_termid 140fields may be updated later if the 141.Fa at_type 142field in 143.Fa au_tid_addr 144is set to AU_IPv4 and the other 145.Fa ai_tid_addr 146fields are all set to zero. 147Creating a new session is done by setting the 148.Fa ai_asid 149field to an unique session value or AU_ASSIGN_ASID. 150These system calls will fail when attempting to change the 151.Fa ai_auid 152or 153.Fa ai_termid 154fields once set to something other than the default values. 155The 156.Fa ai_flags 157field may be updated only according to local access control 158policy but this is usually accomplished with 159.Xr auditon 2 160using the A_SETSFLAGS command. 161The audit preselection masks may be changed at any time 162but are usually updated with 163.Xr auditon 2 164.Pp 165The 166.Fn setaudit 167system call (NOW DEPRECATED) 168sets the active audit session state for the current process via the 169.Vt auditinfo_t 170pointed to by 171.Fa auditinfo . 172The 173.Fn setaudit_addr 174system call 175sets extended state via 176.Fa auditinfo_addr 177and 178.Fa length . 179.Pp 180The 181.Fa auditinfo_t 182data structure (NOW DEPRECATED) is defined as follows: 183.nf 184.Bd -literal -offset indent 185struct auditinfo { 186 au_id_t ai_auid; /* Audit user ID */ 187 au_mask_t ai_mask; /* Audit masks */ 188 au_tid_t ai_termid; /* Terminal ID */ 189 au_asid_t ai_asid; /* Audit session ID */ 190}; 191typedef struct auditinfo auditinfo_t; 192.Ed 193.fi 194.Pp 195The 196.Fa au_termid_t 197data structure (NOW DEPRECATED) defines the Terminal ID recorded with every 198event caused by the process. 199It is defined as follows: 200.nf 201.Bd -literal -offset indent 202struct au_tid { 203 dev_t port; 204 u_int32_t machine; 205}; 206typedef struct au_tid au_tid_t; 207.Ed 208.fi 209.Sh RETURN VALUES 210.Rv -std setaudit_addr 211.Sh ERRORS 212.Bl -tag -width Er 213.It Bq Er EFAULT 214A failure occurred while data transferred to or from 215the kernel failed. 216.It Bq Er EINVAL 217Illegal argument was passed by a system call. 218.It Bq Er EPERM 219The process does not have sufficient permission to complete 220the operation. 221.El 222.Sh SEE ALSO 223.Xr audit 2 , 224.Xr auditon 2 , 225.Xr getaudit 2 , 226.Xr getauid 2 , 227.Xr setauid 2 , 228.Xr libbsm 3 229.Sh HISTORY 230The OpenBSM implementation was created by McAfee Research, the security 231division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 232It was subsequently adopted by the TrustedBSD Project as the foundation for 233the OpenBSM distribution. 234.Pp 235.Fn setaudit_addr 236replaced 237.Fn setaudit 238in Mac OS X 10.7 to support longer terminal addresses such as those used 239by IP version 6. 240.Fn setaudit 241is now deprecated and 242.Fn setaudit_addr 243should be used instead. 244.Sh AUTHORS 245.An -nosplit 246This software was created by McAfee Research, the security research division 247of McAfee, Inc., under contract to Apple Computer Inc. 248Additional authors include 249.An Wayne Salamon , 250.An Robert Watson , 251and SPARTA Inc. 252.Pp 253The Basic Security Module (BSM) interface to audit records and audit event 254stream format were defined by Sun Microsystems. 255.Pp 256This manual page was written by 257.An Robert Watson Aq [email protected] 258and 259.An Stacey Son Aq [email protected] . 260