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 struct auditinfo {
  63         au_id_t        ai_auid;         /* Audit user ID */
  64         au_mask_t      ai_mask;         /* Audit masks */
  65         au_tid_t       ai_termid;       /* Terminal ID */
  66         au_asid_t      ai_asid;         /* Audit session ID */
  67 };
  68 typedef struct auditinfo        auditinfo_t;
  69 .in
  70 .fi
  71 .Pp
  72 The
  73 .Fa ai_auid
  74 variable contains the audit identifier which is recorded in the audit log for
  75 each event the process caused.
  76 .Pp
  77 The
  78 .Fa au_mask_t
  79 data structure defines the bit mask for auditing successful and failed events
  80 out of the predefined list of event classes. It is defined as follows:
  81 .nf
  82 .in +4n
  83 struct au_mask {
  84         unsigned int    am_success;     /* success bits */
  85         unsigned int    am_failure;     /* failure bits */
  86 };
  87 typedef struct au_mask  au_mask_t;
  88 .in
  89 .fi
  90 .Pp
  91 The
  92 .Fa au_termid_t
  93 data structure defines the Terminal ID recorded with every event caused by the
  94 process. It is defined as follows:
  95 .nf
  96 .in +4n
  97 struct au_tid {
  98         dev_t           port;
  99         u_int32_t       machine;
 100 };
 101 typedef struct au_tid   au_tid_t;
 102 .in
 103 .fi
 104 .Pp
 105 The
 106 .Fa ai_asid
 107 variable contains the audit session ID which is recorded with every event
 108 caused by the process.
 109 .Pp
 110 The
 111 .Fn getaudit_addr
 112 system call
 113 uses the expanded
 114 .Fa auditinfo_addr_t
 115 data structure supports Terminal IDs with larger addresses such as those used
 116 in IP version 6.  It is defined as follows:
 117 .nf
 118 .in +4n
 119 struct auditinfo_addr {
 120         au_id_t         ai_auid;        /* Audit user ID. */
 121         au_mask_t       ai_mask;        /* Audit masks. */
 122         au_tid_addr_t   ai_termid;      /* Terminal ID. */
 123         au_asid_t       ai_asid;        /* Audit session ID. */
 124         u_int64_t       ai_flags;       /* Audit session flags. */
 125 };
 126 typedef struct auditinfo_addr   auditinfo_addr_t;
 127 .in
 128 .fi
 129 .Pp
 130 The
 131 .Fa au_tid_addr_t
 132 data structure which includes a larger address storage field and an additional
 133 field with the type of address stored:
 134 .nf
 135 .in +4n
 136 struct au_tid_addr {
 137         dev_t           at_port;
 138         u_int32_t       at_type;
 139         u_int32_t       at_addr[4];
 140 };
 141 typedef struct au_tid_addr      au_tid_addr_t;
 142 .in
 143 .fi
 144 .Pp
 145 Without appropriate privilege the audit mask fields will be set to all
 146 ones.
 147 .Sh RETURN VALUES
 148 .Rv -std getaudit getaudit_addr
 149 .Sh ERRORS
 150 The
 151 .Fn getaudit
 152 function will fail if:
 153 .Bl -tag -width Er
 154 .It Bq Er EFAULT
 155 A failure occurred while data transferred to or from
 156 the kernel failed.
 157 .It Bq Er EINVAL
 158 Illegal argument was passed by a system call.
 159 .It Bq Er EOVERFLOW
 160 The
 161 .Fa length
 162 argument indicates an overflow condition will occur.
 163 .It Bq Er ERANGE
 164 The address is too big and, therefore,
 165 .Fn getaudit_addr
 166 should be used instead.
 167 .El
 168 .Sh SEE ALSO
 169 .Xr audit 2 ,
 170 .Xr auditon 2 ,
 171 .Xr getauid 2 ,
 172 .Xr setaudit 2 ,
 173 .Xr setauid 2 ,
 174 .Xr libbsm 3
 175 .Sh HISTORY
 176 The OpenBSM implementation was created by McAfee Research, the security
 177 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 178 It was subsequently adopted by the TrustedBSD Project as the foundation for
 179 the OpenBSM distribution.
 180 .Sh AUTHORS
 181 .An -nosplit
 182 This software was created by McAfee Research, the security research division
 183 of McAfee, Inc., under contract to Apple Computer Inc.
 184 Additional authors include
 185 .An Wayne Salamon ,
 186 .An Robert Watson ,
 187 and SPARTA Inc.
 188 .Pp
 189 The Basic Security Module (BSM) interface to audit records and audit event
 190 stream format were defined by Sun Microsystems.
 191 .Pp
 192 This manual page was written by
 193 .An Robert Watson Aq rwatson@FreeBSD.org .