bsd/man/man2/setaudit_addr.2

   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
  40 The
  41 .Fn setaudit_addr
  42 system call
  43 uses the
  44 .Fa auditinfo_addr_t
  45 data structure for the
  46 .Fa auditinfo_addr
  47 argument which supports Terminal IDs with large addresses
  48 such as those used in IP version 6.  It is defined as follows:
  49 .nf
  50 .in +4n
  51 struct 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 };
  58 typedef struct auditinfo_addr   auditinfo_addr_t;
  59 .in
  60 .fi
  61 .Pp
  62 The
  63 .Fa ai_auid
  64 variable contains the audit identifier which is recorded in the audit log for
  65 each event the process caused. The value of AU_DEFAUDITID (-1) should not be
  66 used.  The exception is if the value of audit identifier is known at the start
  67 of the session but will be determined and set later. Until
  68 .Fa ai_auid
  69 is set to something other than AU_DEFAUDITID any audit events
  70 generated by the system with be filtered by the non-attributed audit
  71 mask.
  72 .Pp
  73 The
  74 .Fa au_mask_t
  75 data structure defines the bit mask for auditing successful and failed events
  76 out of the predefined list of event classes. It is defined as follows:
  77 .nf
  78 .in +4n
  79 struct au_mask {
  80         unsigned int    am_success;     /* success bits */
  81         unsigned int    am_failure;     /* failure bits */
  82 };
  83 typedef struct au_mask  au_mask_t;
  84 .in
  85 .fi
  86 .Pp
  87 The
  88 .Fa au_tid_addr_t
  89 data structure includes a larger address storage field and an additional
  90 field with the type of address stored:
  91 .nf
  92 .in +4n
  93 struct au_tid_addr {
  94         dev_t           at_port;
  95         u_int32_t       at_type;
  96         u_int32_t       at_addr[4];
  97 };
  98 typedef struct au_tid_addr      au_tid_addr_t;
  99 .in
 100 .fi
 101 .Pp
 102 The
 103 .Fa ai_asid
 104 variable contains the audit session ID which is recorded with every event
 105 caused by the process.  It can be any value in the range 1 to PID_MAX (99999).
 106 If the value of AU_ASSIGN_ASID is used for
 107 .Fa ai_asid
 108 a unique session ID will be generated by the kernel.
 109 The audit session ID will be returned in the
 110 .Fa ai_asid
 111 field on success.
 112 .Pp
 113 The
 114 .Fa ai_flags
 115 field is opaque to the kernel and can be used to store flags associated
 116 with the audit session.  Please see the
 117 .Ao Pa bsm/audit_session.h Ac
 118 header file
 119 for more infomration and flag definitions for this platform.
 120 .Pp
 121 The
 122 .Fa setaudit_addr
 123 system call require an appropriate privilege to complete.
 124 .Pp
 125 This system call should only be called once at the start of a new
 126 session and not again during the same session to update the session
 127 information.
 128 There are some exceptions, however.
 129 The
 130 .Fa ai_auid
 131 field may be updated later if initially set to the value of
 132 AU_DEFAUDITID (-1).
 133 Likewise, the
 134 .Fa ai_termid
 135 fields may be updated later if the
 136 .Fa at_type
 137 field in
 138 .Fa au_tid_addr
 139 is set to AU_IPv4 and the other
 140 .Fa ai_tid_addr
 141 fields are all set to zero.
 142 Creating a new session is done by setting the
 143 .Fa ai_asid
 144 field to an unique session value or AU_ASSIGN_ASID.
 145 These system calls will fail when attempting to change the
 146 .Fa ai_auid
 147 or
 148 .Fa ai_termid
 149 fields once set to something other than the default values.
 150 The
 151 .Fa ai_flags
 152 field may be updated only according to local access control
 153 policy but this is usually accomplished with
 154 .Xr auditon 2
 155 using the A_SETSFLAGS command.
 156 The audit preselection masks may be changed at any time
 157 but are usually updated with
 158 .Xr auditon 2
 159 .Pp
 160 The
 161 .Fn setaudit
 162 system call (NOW DEPRECATED)
 163 sets the active audit session state for the current process via the
 164 .Vt auditinfo_t
 165 pointed to by
 166 .Fa auditinfo .
 167 The
 168 .Fn setaudit_addr
 169 system call
 170 sets extended state via
 171 .Fa auditinfo_addr
 172 and
 173 .Fa length .
 174 .Pp
 175 The
 176 .Fa auditinfo_t
 177 data structure (NOW DEPRECATED) is defined as follows:
 178 .nf
 179 .in +4n
 180 struct auditinfo {
 181         au_id_t        ai_auid;         /* Audit user ID */
 182         au_mask_t      ai_mask;         /* Audit masks */
 183         au_tid_t       ai_termid;       /* Terminal ID */
 184         au_asid_t      ai_asid;         /* Audit session ID */
 185 };
 186 typedef struct auditinfo        auditinfo_t;
 187 .in
 188 .fi
 189 .Pp
 190 The
 191 .Fa au_termid_t
 192 data structure (NOW DEPRECATED) defines the Terminal ID recorded with every
 193 event caused by the process. It is defined as follows:
 194 .nf
 195 .in +4n
 196 struct au_tid {
 197         dev_t           port;
 198         u_int32_t       machine;
 199 };
 200 typedef struct au_tid   au_tid_t;
 201 .in
 202 .fi
 203 .Sh RETURN VALUES
 204 .Rv -std setaudit_addr
 205 .Sh ERRORS
 206 .Bl -tag -width Er
 207 .It Bq Er EFAULT
 208 A failure occurred while data transferred to or from
 209 the kernel failed.
 210 .It Bq Er EINVAL
 211 Illegal argument was passed by a system call.
 212 .It Bq Er EPERM
 213 The process does not have sufficient permission to complete
 214 the operation.
 215 .El
 216 .Sh SEE ALSO
 217 .Xr audit 2 ,
 218 .Xr auditon 2 ,
 219 .Xr getaudit 2 ,
 220 .Xr getauid 2 ,
 221 .Xr setauid 2 ,
 222 .Xr libbsm 3
 223 .Sh HISTORY
 224 The OpenBSM implementation was created by McAfee Research, the security
 225 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 226 It was subsequently adopted by the TrustedBSD Project as the foundation for
 227 the OpenBSM distribution.
 228 .Pp
 229 .Fn setaudit_addr
 230 replaced
 231 .Fn setaudit
 232 in Mac OS X 10.7 to support longer terminal addresses such as those used
 233 by IP version 6.
 234 .Fn setaudit
 235 is now deprecated and
 236 .Fn setaudit_addr
 237 should be used instead.
 238 .Sh AUTHORS
 239 .An -nosplit
 240 This software was created by McAfee Research, the security research division
 241 of McAfee, Inc., under contract to Apple Computer Inc.
 242 Additional authors include
 243 .An Wayne Salamon ,
 244 .An Robert Watson ,
 245 and SPARTA Inc.
 246 .Pp
 247 The Basic Security Module (BSM) interface to audit records and audit event
 248 stream format were defined by Sun Microsystems.
 249 .Pp
 250 This manual page was written by
 251 .An Robert Watson Aq rwatson@FreeBSD.org
 252 and
 253 .An Stacey Son Aq sson@FreeBSD.org .