bsd/man/man2/getaudit_addr.2

   1 .\"
   2 .\" Copyright (c) 2008-2011 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_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. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .Dd March 6, 2011
  29 .Dt GETAUDIT_ADDR 2
  30 .Os
  31 .Sh NAME
  32 .Nm getaudit_addr ,
  33 .Nm getaudit(NOW DEPRECATED)
  34 .Nd "retrieve audit session state"
  35 .Sh SYNOPSIS
  36 .In bsm/audit.h
  37 .In bsm/audit_session.h
  38 .Ft int
  39 .Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
  40 .Sh SYNOPSIS (NOW DEPRECATED)
  41 .In bsm/audit.h
  42 .Ft int
  43 .Fn getaudit "auditinfo_t *auditinfo"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn getaudit_addr
  47 system call
  48 retrieves extended state via
  49 .Fa auditinfo_addr
  50 and
  51 .Fa length .
  52 It
  53 uses the
  54 .Fa auditinfo_addr_t
  55 data structure supports Terminal IDs incuding those with larger addresses such
  56 as those used in IP version 6.  It is defined as follows:
  57 .nf
  58 .in +4n
  59 struct auditinfo_addr {
  60         au_id_t         ai_auid;        /* Audit user ID. */
  61         au_mask_t       ai_mask;        /* Audit masks. */
  62         au_tid_addr_t   ai_termid;      /* Terminal ID. */
  63         au_asid_t       ai_asid;        /* Audit session ID. */
  64         u_int64_t       ai_flags;       /* Audit session flags. */
  65 };
  66 typedef struct auditinfo_addr   auditinfo_addr_t;
  67 .in
  68 .fi
  69 .Pp
  70 The
  71 .Fa ai_auid
  72 variable contains the audit identifier which is recorded in the audit log for
  73 each event the process caused.
  74 .Pp
  75 The
  76 .Fa au_mask_t
  77 data structure defines the bit mask for auditing successful and failed events
  78 out of the predefined list of event classes. It is defined as follows:
  79 .nf
  80 .in +4n
  81 struct au_mask {
  82         unsigned int    am_success;     /* success bits */
  83         unsigned int    am_failure;     /* failure bits */
  84 };
  85 typedef struct au_mask  au_mask_t;
  86 .in
  87 .fi
  88 .Pp
  89 The
  90 .Fa au_tid_addr_t
  91 data structure which includes a larger address storage field and an additional
  92 field with the type of address stored:
  93 .nf
  94 .in +4n
  95 struct au_tid_addr {
  96         dev_t           at_port;
  97         u_int32_t       at_type;
  98         u_int32_t       at_addr[4];
  99 };
 100 typedef struct au_tid_addr      au_tid_addr_t;
 101 .in
 102 .fi
 103 .Pp
 104 The
 105 .Fa ai_asid
 106 variable contains the audit session ID which is recorded with every event
 107 caused by the process.
 108 .Pp
 109 The
 110 .Fa ai_flags
 111 variable contains flags that are opaque to the kernel and used by various
 112 consumers of the
 113 .Fa auditinfo_addr
 114 data.  Please see the
 115 .Ao Pa bsm/audit_session.h Ac
 116 header file for more information
 117 and flag definitions for this platform.
 118 .Pp
 119 Without appropriate privilege the audit mask fields will be set to all
 120 ones.
 121 .Pp
 122 The
 123 .Fn getaudit
 124 system call (NOW DEPRECATED)
 125 retrieves the active audit session state for the current process via the
 126 .Vt auditinfo_t
 127 pointed to by
 128 .Fa auditinfo .
 129 .Pp
 130 The
 131 .Fa auditinfo_t
 132 data structure (NOW DEPRECATED) is defined as follows:
 133 .nf
 134 .in +4n
 135 struct auditinfo {
 136         au_id_t        ai_auid;         /* Audit user ID */
 137         au_mask_t      ai_mask;         /* Audit masks */
 138         au_tid_t       ai_termid;       /* Terminal ID */
 139         au_asid_t      ai_asid;         /* Audit session ID */
 140 };
 141 typedef struct auditinfo        auditinfo_t;
 142 .in
 143 .fi
 144 .Pp
 145 The
 146 .Fa au_termid_t
 147 data structure (NOW DEPRECATED) defines the Terminal ID recorded with
 148 every event caused by the process. It is defined as follows:
 149 .nf
 150 .in +4n
 151 struct au_tid {
 152         dev_t           port;
 153         u_int32_t       machine;
 154 };
 155 typedef struct au_tid   au_tid_t;
 156 .in
 157 .fi
 158 .Sh RETURN VALUES
 159 .Rv -std getaudit_addr
 160 .Sh ERRORS
 161 The
 162 .Fn getaudit_addr
 163 function will fail if:
 164 .Bl -tag -width Er
 165 .It Bq Er EFAULT
 166 A failure occurred while data transferred to or from
 167 the kernel failed.
 168 .It Bq Er EINVAL
 169 Illegal argument was passed by a system call.
 170 .It Bq Er EOVERFLOW
 171 The
 172 .Fa length
 173 argument indicates an overflow condition will occur.
 174 .It Bq Er ERANGE
 175 The address is too big.
 176 .El
 177 .Sh SEE ALSO
 178 .Xr audit 2 ,
 179 .Xr auditon 2 ,
 180 .Xr getauid 2 ,
 181 .Xr setaudit 2 ,
 182 .Xr setauid 2 ,
 183 .Xr libbsm 3
 184 .Sh HISTORY
 185 The OpenBSM implementation was created by McAfee Research, the security
 186 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 187 It was subsequently adopted by the TrustedBSD Project as the foundation for
 188 the OpenBSM distribution.
 189 .Pp
 190 .Fn getaudit_addr
 191 replaced
 192 .Fn getaudit
 193 in Mac OS X 10.7 to support longer terminal addresses such as those used
 194 by IP version 6.
 195 .Fn getaudit
 196 is now deprecated and
 197 .Fn getaudit_addr
 198 should be used instead.
 199 .Sh AUTHORS
 200 .An -nosplit
 201 This software was created by McAfee Research, the security research division
 202 of McAfee, Inc., under contract to Apple Computer Inc.
 203 Additional authors include
 204 .An Wayne Salamon ,
 205 .An Robert Watson ,
 206 and SPARTA Inc.
 207 .Pp
 208 The Basic Security Module (BSM) interface to audit records and audit event
 209 stream format were defined by Sun Microsystems.
 210 .Pp
 211 This manual page was written by
 212 .An Robert Watson Aq rwatson@FreeBSD.org
 213 and
 214 .An Stacey Son Aq sson@FreeBSD.org .