contrib/openbsm/man/setaudit.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 .\" $P4: //depot/projects/trustedbsd/openbsm/man/setaudit.2#10 $
  28 .\"
  29 .Dd April 19, 2005
  30 .Dt SETAUDIT 2
  31 .Os
  32 .Sh NAME
  33 .Nm setaudit ,
  34 .Nm setaudit_addr
  35 .Nd "set audit session state"
  36 .Sh SYNOPSIS
  37 .In bsm/audit.h
  38 .Ft int
  39 .Fn setaudit "auditinfo_t *auditinfo"
  40 .Ft int
  41 .Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn setaudit
  45 system call
  46 sets the active audit session state for the current process via the
  47 .Vt auditinfo_t
  48 pointed to by
  49 .Fa auditinfo .
  50 The
  51 .Fn setaudit_addr
  52 system call
  53 sets extended state via
  54 .Fa auditinfo_addr
  55 and
  56 .Fa length .
  57 .Pp
  58 The
  59 .Fa auditinfo_t
  60 data structure is defined as follows:
  61 .nf
  62 .in +4n
  63
  64 struct auditinfo {
  65         au_id_t        ai_auid;         /* Audit user ID */
  66         au_mask_t      ai_mask;         /* Audit masks */
  67         au_tid_t       ai_termid;       /* Terminal ID */
  68         au_asid_t      ai_asid;         /* Audit session ID */
  69 };
  70 typedef struct auditinfo        auditinfo_t;
  71 .in
  72 .fi
  73 .Pp
  74 The
  75 .Fa ai_auid
  76 variable contains the audit identifier which is recorded in the audit log for
  77 each event the process caused.
  78 .PP
  79
  80 The
  81 .Fa au_mask_t
  82 data structure defines the bit mask for auditing successful and failed events
  83 out of the predefined list of event classes. It is defined as follows:
  84 .nf
  85 .in +4n
  86
  87 struct au_mask {
  88         unsigned int    am_success;     /* success bits */
  89         unsigned int    am_failure;     /* failure bits */
  90 };
  91 typedef struct au_mask  au_mask_t;
  92 .in
  93 .fi
  94 .PP
  95
  96 The
  97 .Fa au_termid_t
  98 data structure defines the Terminal ID recorded with every event caused by the
  99 process. It is defined as follows:
 100 .nf
 101 .in +4n
 102
 103 struct au_tid {
 104         dev_t           port;
 105         u_int32_t       machine;
 106 };
 107 typedef struct au_tid   au_tid_t;
 108
 109 .in
 110 .fi
 111 .PP
 112 The
 113 .Fa ai_asid
 114 variable contains the audit session ID which is recorded with every event
 115 caused by the process.
 116 .Pp
 117 The
 118 .Fn setaudit_addr
 119 system call
 120 uses the expanded
 121 .Fa auditinfo_addr_t
 122 data structure supports Terminal IDs with larger addresses such as those used
 123 in IP version 6.  It is defined as follows:
 124 .nf
 125 .in +4n
 126
 127 struct auditinfo_addr {
 128         au_id_t         ai_auid;        /* Audit user ID. */
 129         au_mask_t       ai_mask;        /* Audit masks. */
 130         au_tid_addr_t   ai_termid;      /* Terminal ID. */
 131         au_asid_t       ai_asid;        /* Audit session ID. */
 132 };
 133 typedef struct auditinfo_addr   auditinfo_addr_t;
 134 .in
 135 .fi
 136 .Pp
 137 The
 138 .Fa au_tid_addr_t
 139 data structure which includes a larger address storage field and an additional
 140 field with the type of address stored:
 141 .nf
 142 .in +4n
 143
 144 struct au_tid_addr {
 145         dev_t           at_port;
 146         u_int32_t       at_type;
 147         u_int32_t       at_addr[4];
 148 };
 149 typedef struct au_tid_addr      au_tid_addr_t;
 150 .in
 151 .fi
 152 .Pp
 153 These system calls require an appropriate privilege to complete.
 154 .Sh RETURN VALUES
 155 .Rv -std setaudit setaudit_addr
 156 .Sh ERRORS
 157 .Bl -tag -width Er
 158 .It Bq Er EFAULT
 159 A failure occurred while data transferred to or from
 160 the kernel failed.
 161 .It Bq Er EINVAL
 162 Illegal argument was passed by a system call.
 163 .It Bq Er EPERM
 164 The process does not have sufficient permission to complete
 165 the operation.
 166 .El
 167 .Sh SEE ALSO
 168 .Xr audit 2 ,
 169 .Xr auditon 2 ,
 170 .Xr getaudit 2 ,
 171 .Xr getauid 2 ,
 172 .Xr setauid 2 ,
 173 .Xr libbsm 3
 174 .Sh HISTORY
 175 The OpenBSM implementation was created by McAfee Research, the security
 176 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
 177 It was subsequently adopted by the TrustedBSD Project as the foundation for
 178 the OpenBSM distribution.
 179 .Sh AUTHORS
 180 .An -nosplit
 181 This software was created by McAfee Research, the security research division
 182 of McAfee, Inc., under contract to Apple Computer Inc.
 183 Additional authors include
 184 .An Wayne Salamon ,
 185 .An Robert Watson ,
 186 and SPARTA Inc.
 187 .Pp
 188 The Basic Security Module (BSM) interface to audit records and audit event
 189 stream format were defined by Sun Microsystems.
 190 .Pp
 191 This manual page was written by
 192 .An Robert Watson Aq rwatson@FreeBSD.org .