contrib/openbsm/libbsm/au_open.3

   1 .\"-
   2 .\" Copyright (c) 2006 Robert N. M. Watson
   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 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd March 4, 2006
  27 .Dt AU_OPEN 3
  28 .Os
  29 .Sh NAME
  30 .Nm au_close ,
  31 .Nm au_close_buffer ,
  32 .Nm au_close_token ,
  33 .Nm au_open ,
  34 .Nm au_write
  35 .Nd "create and commit audit records"
  36 .Sh LIBRARY
  37 .Lb libbsm
  38 .Sh SYNOPSIS
  39 .In bsm/libbsm.h
  40 .Ft int
  41 .Fn au_open void
  42 .Ft int
  43 .Fn au_write "int d" "token_t *tok"
  44 .Ft int
  45 .Fn au_close "int d" "int keep" "short event"
  46 .Ft int
  47 .Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen"
  48 .Ft int
  49 .Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen"
  50 .Sh DESCRIPTION
  51 These interfaces allow applications to allocate audit records, construct a
  52 record using a series of tokens, and commit the audit record to the system
  53 event log.
  54 An extension API is also provided to commit the record to an in-memory
  55 buffer rather than the system audit log.
  56 .Pp
  57 The
  58 .Fn au_open
  59 interface allocates a new audit record descriptor.
  60 .Pp
  61 The
  62 .Fn au_write
  63 interface adds a token to an allocated audit descriptor.
  64 When a token has been successfully added to a record, the caller no longer
  65 owns the token memory, and does not need to free it directly via a call to
  66 .Xr au_free_token 3 .
  67 .Pp
  68 The
  69 .Fn au_close
  70 function is used to commit an audit record to the system audit log, or
  71 abandon the record.
  72 In either cases, all resources associated with the record will be released.
  73 The
  74 .Fa keep
  75 argument determines the behavior: a value of
  76 .Dv AU_TO_WRITE
  77 causes the record to be committed; a value of
  78 .Dv AU_TO_NO_WRITE
  79 causes it to be abandoned.
  80 When the audit record is committed, a BSM header will be inserted before
  81 tokens added to the record, using the event identifier passed via
  82 .Fa event ,
  83 and a trailer added to the end.
  84 Committing a record to the system audit log requires privilege.
  85 .Pp
  86 The
  87 .Fn au_close_buffer
  88 function writes the resulting record to an in-memory buffer of size
  89 .Fa *buflen ;
  90 it will write back the filled buffer length into the same variable.
  91 The argument
  92 .Fa event
  93 is the event identifier to use in the record header.
  94 .Pp
  95 The
  96 .Fn au_close_token
  97 function generates the BSM stream output for a single token,
  98 .Fa tok ,
  99 in the passed buffer
 100 .Fa buffer .
 101 The initial buffer size and resulting data size are passed via
 102 .Fa *buflen .
 103 The
 104 .Fn au_close_token
 105 function
 106 will free the token before returning.
 107 .Sh RETURN VALUES
 108 The function
 109 .Fn au_open
 110 returns a non-negative audit record descriptor number on success, or a
 111 negative value on failure, along with error information in
 112 .Va errno .
 113 .Pp
 114 The functions
 115 .Fn au_write ,
 116 .Fn au_close ,
 117 .Fn au_close_buffer ,
 118 and
 119 .Fn au_close_token
 120 return 0 on success, or a negative value on failure, along with error
 121 information in
 122 .Va errno .
 123 .Sh SEE ALSO
 124 .Xr audit_submit 3 ,
 125 .Xr libbsm 3
 126 .Sh HISTORY
 127 The OpenBSM implementation was created by McAfee Research, the security
 128 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 129 It was subsequently adopted by the TrustedBSD Project as the foundation for
 130 the OpenBSM distribution.
 131 .Sh AUTHORS
 132 .An -nosplit
 133 This software was created by
 134 .An Robert Watson ,
 135 .An Wayne Salamon ,
 136 and
 137 .An Suresh Krishnaswamy
 138 for McAfee Research, the security research division of McAfee,
 139 Inc., under contract to Apple Computer, Inc.
 140 .Pp
 141 The Basic Security Module (BSM) interface to audit records and audit event
 142 stream format were defined by Sun Microsystems.
 143 .Sh BUGS
 144 Currently,
 145 .Fn au_open
 146 does not reserve kernel resources necessary to commit the record to the
 147 trail; on systems supporting
 148 .Fn au_close ,
 149 the call will block until resources are available to commit the record.
 150 However, this leads to the possibility of an action being permitted without
 151 the record being guaranteed to go to disk.
 152 Ideally,
 153 .Fn au_open
 154 would reserve resources necessary to commit any submitted record, releasing
 155 them on
 156 .Fn au_close .