bsd/man/man2/getaudit.2

   1 .\"
   2 .\" Copyright (c) 2008-2009 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, 2009
  29 .Dt GETAUDIT 2
  30 .Os
  31 .Sh NAME
  32 .Nm getaudit ,
  33 .Nm getaudit_addr
  34 .Nd "retrieve audit session state"
  35 .Sh SYNOPSIS
  36 .In bsm/audit.h
  37 .Ft int
  38 .Fn getaudit "auditinfo_t *auditinfo"
  39 .Ft int
  40 .Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn getaudit
  44 system call
  45 retrieves the active audit session state for the current process via the
  46 .Vt auditinfo_t
  47 pointed to by
  48 .Fa auditinfo .
  49 The
  50 .Fn getaudit_addr
  51 system call
  52 retrieves extended state via
  53 .Fa auditinfo_addr
  54 and
  55 .Fa length .
  56 .Pp
  57 The
  58 .Fa auditinfo_t
  59 data structure is defined as follows:
  60 .nf
  61 .in +4n
  62
  63 struct auditinfo {
  64         au_id_t        ai_auid;         /* Audit user ID */
  65         au_mask_t      ai_mask;         /* Audit masks */
  66         au_tid_t       ai_termid;       /* Terminal ID */
  67         au_asid_t      ai_asid;         /* Audit session ID */
  68 };
  69 typedef struct auditinfo        auditinfo_t;
  70 .in
  71 .fi
  72 .Pp
  73 The
  74 .Fa ai_auid
  75 variable contains the audit identifier which is recorded in the audit log for
  76 each event the process caused.
  77 .PP
  78
  79 The
  80 .Fa au_mask_t
  81 data structure defines the bit mask for auditing successful and failed events
  82 out of the predefined list of event classes. It is defined as follows:
  83 .nf
  84 .in +4n
  85
  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
  95 The
  96 .Fa au_termid_t
  97 data structure defines the Terminal ID recorded with every event caused by the
  98 process. It is defined as follows:
  99 .nf
 100 .in +4n
 101
 102 struct au_tid {
 103         dev_t           port;
 104         u_int32_t       machine;
 105 };
 106 typedef struct au_tid   au_tid_t;
 107 .in
 108 .fi
 109 .PP
 110
 111 The
 112 .Fa ai_asid
 113 variable contains the audit session ID which is recorded with every event
 114 caused by the process.
 115 .Pp
 116 The
 117 .Fn getaudit_addr
 118 system call
 119 uses the expanded
 120 .Fa auditinfo_addr_t
 121 data structure supports Terminal IDs with larger addresses such as those used
 122 in IP version 6.  It is defined as follows:
 123 .nf
 124 .in +4n
 125
 126 struct auditinfo_addr {
 127         au_id_t         ai_auid;        /* Audit user ID. */
 128         au_mask_t       ai_mask;        /* Audit masks. */
 129         au_tid_addr_t   ai_termid;      /* Terminal ID. */
 130         au_asid_t       ai_asid;        /* Audit session ID. */
 131         u_int64_t       ai_flags;       /* Audit session flags. */
 132 };
 133 typedef struct auditinfo_addr   auditinfo_addr_t;
 134 .in
 135 .fi
 136 .Pp
 137
 138 The
 139 .Fa au_tid_addr_t
 140 data structure which includes a larger address storage field and an additional
 141 field with the type of address stored:
 142 .nf
 143 .in +4n
 144
 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 Without appropriate privilege the audit mask fields will be set to all
 155 ones.
 156 .Sh RETURN VALUES
 157 .Rv -std getaudit getaudit_addr
 158 .Sh ERRORS
 159 The
 160 .Fn getaudit
 161 function will fail if:
 162 .Bl -tag -width Er
 163 .It Bq Er EFAULT
 164 A failure occurred while data transferred to or from
 165 the kernel failed.
 166 .It Bq Er EINVAL
 167 Illegal argument was passed by a system call.
 168 .It Bq Er EOVERFLOW
 169 The
 170 .Fa length
 171 argument indicates an overflow condition will occur.
 172 .It Bq Er ERANGE
 173 The address is too big and, therefore,
 174 .Fn getaudit_addr
 175 should be used instead.
 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 .Sh AUTHORS
 190 .An -nosplit
 191 This software was created by McAfee Research, the security research division
 192 of McAfee, Inc., under contract to Apple Computer Inc.
 193 Additional authors include
 194 .An Wayne Salamon ,
 195 .An Robert Watson ,
 196 and SPARTA Inc.
 197 .Pp
 198 The Basic Security Module (BSM) interface to audit records and audit event
 199 stream format were defined by Sun Microsystems.
 200 .Pp
 201 This manual page was written by
 202 .An Robert Watson Aq rwatson@FreeBSD.org .