contrib/openbsm/libbsm/audit_submit.3

   1 .\"
   2 .\" Copyright (c) 2006 Christian S.J. Peron
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   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 APPLE AND ITS 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 APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
  19 .\" 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,
  23 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  24 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/audit_submit.3#19 $
  28 .\"
  29 .Dd January 18, 2008
  30 .Dt AUDIT_SUBMIT 3
  31 .Os
  32 .Sh NAME
  33 .Nm audit_submit
  34 .Nd "general purpose audit record submission"
  35 .Sh LIBRARY
  36 .Lb libbsm
  37 .Sh SYNOPSIS
  38 .In bsm/libbsm.h
  39 .Ft int
  40 .Fo audit_submit
  41 .Fa "short au_event" "au_id_t auid" "char status"
  42 .Fa "int reterr" "const char * restrict format" ...
  43 .Fc
  44 .Sh DESCRIPTION
  45 The
  46 .Fn audit_submit
  47 function provides a generic programming interface for audit record submission.
  48 This audit record will contain a header, subject token, an optional text token,
  49 return token, and a trailer.
  50 The header will contain the event class specified by
  51 .Fa au_event .
  52 The subject token will be generated based on
  53 .Fa auid .
  54 The return token is dependent on the
  55 .Fa status
  56 and
  57 .Fa reterr
  58 arguments; unlike the argument to
  59 .Xr au_to_return ,
  60 .Fa reterr
  61 should be a local rather than BSM error number.
  62 Optionally, a text token will be created as a part of this record.
  63 .Pp
  64 Text token output is under the control of a
  65 .Fa format
  66 string that specifies how subsequent arguments (or arguments accessed via the
  67 variable-length argument facilities of
  68 .Xr stdarg 3 )
  69 are converted for output.
  70 If
  71 .Fa format
  72 is
  73 .Dv NULL ,
  74 then no text token is created in the audit record.
  75 .Pp
  76 It should be noted that
  77 .Fn audit_submit
  78 assumes that
  79 .Xr setaudit 2 ,
  80 or
  81 .Xr setaudit_addr 2
  82 has already been called.
  83 As a direct result, the terminal ID for the
  84 subject will be retrieved from the kernel via
  85 .Xr getaudit 2 ,
  86 or
  87 .Xr getaudit_addr 2 .
  88 .Sh RETURN VALUES
  89 If successful,
  90 .Nm
  91 will return zero.
  92 Otherwise a -1 is returned and the global variable
  93 .Va errno
  94 is set to indicate the error.
  95 .Sh EXAMPLES
  96 .Bd -literal -offset indent
  97 #include <bsm/audit.h>
  98 #include <bsm/libbsm.h>
  99 #include <bsm/audit_uevents.h>
 100
 101 #include <stdio.h>
 102 #include <stdarg.h>
 103 #include <errno.h>
 104
 105 void
 106 audit_bad_su(char *from_login, char *to_login)
 107 {
 108         struct auditinfo_addr aia;
 109         struct auditinfo ai;
 110         au_id_t aid;
 111         int error;
 112
 113         error = getaudit_addr(&aia, sizeof(aia));
 114         if (error < 0 && errno == ENOSYS) {
 115                 error = getaudit(&ai);
 116                 if (error < 0)
 117                         err(1, "getaudit");
 118                 aid = ai.ai_auid;
 119         } else if (error < 0)
 120                 err(1, "getaudit_addr");
 121         else
 122                 aid = aia.ai_auid;
 123         error = audit_submit(AUE_su, aid, EPERM, 1,
 124             "bad su from %s to %s", from_login, to_login);
 125         if (error != 0)
 126                 err(1, "audit_submit");
 127 }
 128 .Ed
 129 .Pp
 130 Will generate the following audit record:
 131 .Bd -literal -offset indent
 132 header,94,1,su(1),0,Mon Apr 17 23:23:59 2006, + 271 msec
 133 subject,root,root,wheel,root,wheel,652,652,0,0.0.0.0
 134 text,bad su from from csjp to root
 135 return,failure : Operation not permitted,1
 136 trailer,94
 137 .Ed
 138 .Sh SEE ALSO
 139 .Xr auditon 2 ,
 140 .Xr getaudit 2 ,
 141 .Xr libbsm 3 ,
 142 .Xr stdarg 3
 143 .Sh HISTORY
 144 The
 145 .Fn audit_submit
 146 function first appeared in OpenBSM version 1.0.
 147 OpenBSM 1.0 was introduced in
 148 .Fx 7.0 .
 149 .Sh AUTHORS
 150 The
 151 .Fn audit_submit
 152 function was written by
 153 .An Christian S.J. Peron Aq csjp@FreeBSD.org .