contrib/openbsm/man/getaudit.2

   1 .\"-
   2 .\" Copyright (c) 2005 Robert N. M. Watson
   3 .\" Copyright (c) 2008 Apple Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd March 14, 2018
  28 .Dt GETAUDIT 2
  29 .Os
  30 .Sh NAME
  31 .Nm getaudit ,
  32 .Nm getaudit_addr
  33 .Nd "retrieve audit session state"
  34 .Sh SYNOPSIS
  35 .In bsm/audit.h
  36 .Ft int
  37 .Fn getaudit "auditinfo_t *auditinfo"
  38 .Ft int
  39 .Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn getaudit
  43 system call
  44 retrieves the active audit session state for the current process via the
  45 .Vt auditinfo_t
  46 pointed to by
  47 .Fa auditinfo .
  48 The
  49 .Fn getaudit_addr
  50 system call
  51 retrieves extended state via
  52 .Fa auditinfo_addr
  53 and
  54 .Fa length .
  55 .Pp
  56 The
  57 .Fa auditinfo_t
  58 data structure is defined as follows:
  59 .Bd -literal -offset indent
  60 struct auditinfo {
  61         au_id_t        ai_auid;         /* Audit user ID */
  62         au_mask_t      ai_mask;         /* Audit masks */
  63         au_tid_t       ai_termid;       /* Terminal ID */
  64         au_asid_t      ai_asid;         /* Audit session ID */
  65         au_asflgs_t    ai_flags;        /* Audit session flags. */
  66 };
  67 typedef struct auditinfo        auditinfo_t;
  68 .Ed
  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.
  79 It is defined as follows:
  80 .Bd -literal -offset indent
  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 .Ed
  87 .Pp
  88 The
  89 .Fa au_termid_t
  90 data structure defines the Terminal ID recorded with every event caused by the
  91 process.
  92 It is defined as follows:
  93 .Bd -literal -offset indent
  94 struct au_tid {
  95         dev_t           port;
  96         u_int32_t       machine;
  97 };
  98 typedef struct au_tid   au_tid_t;
  99 .Ed
 100 .Pp
 101 The
 102 .Fa ai_asid
 103 variable contains the audit session ID which is recorded with every event
 104 caused by the process.
 105 .Pp
 106 The
 107 .Fn getaudit_addr
 108 system call
 109 uses the expanded
 110 .Fa auditinfo_addr_t
 111 data structure and supports Terminal IDs with larger addresses
 112 such as those used in IP version 6.
 113 It is defined as follows:
 114 .Bd -literal -offset indent
 115 struct auditinfo_addr {
 116         au_id_t         ai_auid;        /* Audit user ID. */
 117         au_mask_t       ai_mask;        /* Audit masks. */
 118         au_tid_addr_t   ai_termid;      /* Terminal ID. */
 119         au_asid_t       ai_asid;        /* Audit session ID. */
 120 };
 121 typedef struct auditinfo_addr   auditinfo_addr_t;
 122 .Ed
 123 .Pp
 124 The
 125 .Fa au_tid_addr_t
 126 data structure which includes a larger address storage field and an additional
 127 field with the type of address stored:
 128 .Bd -literal -offset indent
 129 struct au_tid_addr {
 130         dev_t           at_port;
 131         u_int32_t       at_type;
 132         u_int32_t       at_addr[4];
 133 };
 134 typedef struct au_tid_addr      au_tid_addr_t;
 135 .Ed
 136 .Pp
 137 These system calls require an appropriate privilege to complete.
 138 .Sh RETURN VALUES
 139 .Rv -std getaudit getaudit_addr
 140 .Sh ERRORS
 141 The
 142 .Fn getaudit
 143 function will fail if:
 144 .Bl -tag -width Er
 145 .It Bq Er EFAULT
 146 A failure occurred while data transferred to or from
 147 the kernel failed.
 148 .It Bq Er EINVAL
 149 Illegal argument was passed by a system call.
 150 .It Bq Er EPERM
 151 The process does not have sufficient permission to complete
 152 the operation.
 153 .It Bq Er EOVERFLOW
 154 The
 155 .Fa length
 156 argument indicates an overflow condition will occur.
 157 .It Bq Er E2BIG
 158 The address is too big and, therefore,
 159 .Fn getaudit_addr
 160 should be used instead.
 161 .El
 162 .Sh SEE ALSO
 163 .Xr audit 2 ,
 164 .Xr auditon 2 ,
 165 .Xr getauid 2 ,
 166 .Xr setaudit 2 ,
 167 .Xr setauid 2 ,
 168 .Xr libbsm 3
 169 .Sh HISTORY
 170 The OpenBSM implementation was created by McAfee Research, the security
 171 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 172 It was subsequently adopted by the TrustedBSD Project as the foundation for
 173 the OpenBSM distribution.
 174 .Sh AUTHORS
 175 .An -nosplit
 176 This software was created by McAfee Research, the security research division
 177 of McAfee, Inc., under contract to Apple Computer Inc.
 178 Additional authors include
 179 .An Wayne Salamon ,
 180 .An Robert Watson ,
 181 and SPARTA Inc.
 182 .Pp
 183 The Basic Security Module (BSM) interface to audit records and audit event
 184 stream format were defined by Sun Microsystems.
 185 .Pp
 186 This manual page was written by
 187 .An Robert Watson Aq rwatson@FreeBSD.org .