bsd/man/man2/setaudit.2

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