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