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 .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_open.3#8 $
  27 .\"
  28 .Dd March 4, 2006
  29 .Dt AU_OPEN 3
  30 .Os
  31 .Sh NAME
  32 .Nm au_close ,
  33 .Nm au_close_buffer ,
  34 .Nm au_close_token ,
  35 .Nm au_open ,
  36 .Nm au_write
  37 .Nd "create and commit audit records"
  38 .Sh LIBRARY
  39 .Lb libbsm
  40 .Sh SYNOPSIS
  41 .In bsm/libbsm.h
  42 .Ft int
  43 .Fn au_open void
  44 .Ft int
  45 .Fn au_write "int d" "token_t *tok"
  46 .Ft int
  47 .Fn au_close "int d" "int keep" "short event"
  48 .Ft int
  49 .Fn au_close_buffer "int d" "short event" "u_char *buffer" "size_t *buflen"
  50 .Ft int
  51 .Fn au_close_token "token_t *tok" "u_char *buffer" "size_t *buflen"
  52 .Sh DESCRIPTION
  53 These interfaces allow applications to allocate audit records, construct a
  54 record using a series of tokens, and commit the audit record to the system
  55 event log.
  56 An extension API is also provided to commit the record to an in-memory
  57 buffer rather than the system audit log.
  58 .Pp
  59 The
  60 .Fn au_open
  61 interface allocates a new audit record descriptor.
  62 .Pp
  63 The
  64 .Fn au_write
  65 interface adds a token to an allocated audit descriptor.
  66 When a token has been successfully added to a record, the caller no longer
  67 owns the token memory, and does not need to free it directly via a call to
  68 .Xr au_free_token 3 .
  69 .Pp
  70 The
  71 .Fn au_close
  72 function is used to commit an audit record to the system audit log, or
  73 abandon the record.
  74 In either cases, all resources associated with the record will be released.
  75 The
  76 .Fa keep
  77 argument determines the behavior: a value of
  78 .Dv AU_TO_WRITE
  79 causes the record to be committed; a value of
  80 .Dv AU_TO_NO_WRITE
  81 causes it to be abandoned.
  82 When the audit record is committed, a BSM header will be inserted before
  83 tokens added to the record, using the event identifier passed via
  84 .Fa event ,
  85 and a trailer added to the end.
  86 Committing a record to the system audit log requires privilege.
  87 .Pp
  88 The
  89 .Fn au_close_buffer
  90 function writes the resulting record to an in-memory buffer of size
  91 .Fa *buflen ;
  92 it will write back the filled buffer length into the same variable.
  93 The argument
  94 .Fa event
  95 is the event identifier to use in the record header.
  96 .Pp
  97 The
  98 .Fn au_close_token
  99 function generates the BSM stream output for a single token,
 100 .Fa tok ,
 101 in the passed buffer
 102 .Fa buffer .
 103 The initial buffer size and resulting data size are passed via
 104 .Fa *buflen .
 105 The
 106 .Fn au_close_token
 107 function
 108 will free the token before returning.
 109 .Sh RETURN VALUES
 110 The function
 111 .Fn au_open
 112 returns a non-negative audit record descriptor number on success, or a
 113 negative value on failure, along with error information in
 114 .Va errno .
 115 .Pp
 116 The functions
 117 .Fn au_write ,
 118 .Fn au_close ,
 119 .Fn au_close_buffer ,
 120 and
 121 .Fn au_close_token
 122 return 0 on success, or a negative value on failure, along with error
 123 information in
 124 .Va errno .
 125 .Sh SEE ALSO
 126 .Xr audit_submit 3 ,
 127 .Xr libbsm 3
 128 .Sh HISTORY
 129 The OpenBSM implementation was created by McAfee Research, the security
 130 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 131 It was subsequently adopted by the TrustedBSD Project as the foundation for
 132 the OpenBSM distribution.
 133 .Sh AUTHORS
 134 .An -nosplit
 135 This software was created by
 136 .An Robert Watson ,
 137 .An Wayne Salamon ,
 138 and
 139 .An Suresh Krishnaswamy
 140 for McAfee Research, the security research division of McAfee,
 141 Inc., under contract to Apple Computer, Inc.
 142 .Pp
 143 The Basic Security Module (BSM) interface to audit records and audit event
 144 stream format were defined by Sun Microsystems.
 145 .Sh BUGS
 146 Currently,
 147 .Fn au_open
 148 does not reserve kernel resources necessary to commit the record to the
 149 trail; on systems supporting
 150 .Fn au_close ,
 151 the call will block until resources are available to commit the record.
 152 However, this leads to the possibility of an action being permitted without
 153 the record being guaranteed to go to disk.
 154 Ideally,
 155 .Fn au_open
 156 would reserve resources necessary to commit any submitted record, releasing
 157 them on
 158 .Fn au_close .