contrib/openbsm/libbsm/au_user.3

   1 .\"-
   2 .\" Copyright (c) 2005-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 April 19, 2005
  27 .Dt AU_USER 3
  28 .Os
  29 .Sh NAME
  30 .Nm setauuser ,
  31 .Nm endauuser ,
  32 .Nm getauuserent ,
  33 .Nm getauuserent_r ,
  34 .Nm getauusernam ,
  35 .Nm getauusernam_r ,
  36 .Nm au_user_mask ,
  37 .Nm getfauditflags
  38 .Nd "look up information from the audit_user database"
  39 .Sh LIBRARY
  40 .Lb libbsm
  41 .Sh SYNOPSIS
  42 .In bsm/libbsm.h
  43 .Ft void
  44 .Fn setauuser void
  45 .Ft void
  46 .Fn endauuser void
  47 .Ft "struct au_user_ent *"
  48 .Fn getauuserent void
  49 .Ft "struct au_user_ent *"
  50 .Fn getauuserent_r "struct au_user_ent *u"
  51 .Ft "struct au_user_ent *"
  52 .Fn getauusernam "const char *name"
  53 .Ft "struct au_user_ent *"
  54 .Fn getauusernam_r "struct au_user_ent *u" "const char *name"
  55 .Ft int
  56 .Fn au_user_mask "char *username" "au_mask_t *mask_p"
  57 .Ft int
  58 .Fo getfauditflags
  59 .Fa "au_mask_t *usremask" "au_mask_t *usrdmask" "au_mask_t *lastmask"
  60 .Fc
  61 .Sh DESCRIPTION
  62 These interfaces may be used to look up information from the
  63 .Xr audit_user 5
  64 database, which describes per-user audit configuration.
  65 Audit user entries are described by a
  66 .Vt au_user_ent ,
  67 which stores the user's name in
  68 .Va au_name ,
  69 events to always audit in
  70 .Va au_always ,
  71 and events never to audit
  72 .Va au_never .
  73 .Pp
  74 The
  75 .Fn getauuserent
  76 function
  77 returns the next user found in the
  78 .Xr audit_user 5
  79 database, or the first if the function has not yet been called.
  80 .Dv NULL
  81 will be returned if no further records are available.
  82 .Pp
  83 The
  84 .Fn getauusernam
  85 function
  86 looks up a user by name.
  87 .Dv NULL
  88 will be returned if no matching class can be found.
  89 .Pp
  90 The
  91 .Fn setauuser
  92 function
  93 resets the iterator through the
  94 .Xr audit_user 5
  95 database, causing the next call to
  96 .Fn getauuserent
  97 to start again from the beginning of the file.
  98 .Pp
  99 The
 100 .Fn endauuser
 101 function
 102 closes the
 103 .Xr audit_user 5
 104 database, if open.
 105 .Pp
 106 The
 107 .Fn au_user_mask
 108 function
 109 calculates a new session audit mask to be returned via
 110 .Fa mask_p
 111 for the user identified by
 112 .Fa username .
 113 If the user audit configuration is not found, the default system audit
 114 properties returned by
 115 .Xr getacflg 3
 116 are used.
 117 The resulting mask may be set via a call to
 118 .Xr setaudit 2
 119 or related variants.
 120 .Pp
 121 The
 122 .Fn getfauditflags
 123 function generates a new process audit state by combining the audit masks
 124 passed as parameters with the system audit masks.
 125 .Sh SEE ALSO
 126 .Xr setaudit 2 ,
 127 .Xr getacflg 3 ,
 128 .Xr libbsm 3 ,
 129 .Xr audit_user 5
 130 .Sh HISTORY
 131 The OpenBSM implementation was created by McAfee Research, the security
 132 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 133 It was subsequently adopted by the TrustedBSD Project as the foundation for
 134 the OpenBSM distribution.
 135 .Sh AUTHORS
 136 .An -nosplit
 137 This software was created by
 138 .An Robert Watson ,
 139 .An Wayne Salamon ,
 140 and
 141 .An Suresh Krishnaswamy
 142 for McAfee Research, the security research division of McAfee,
 143 Inc., under contract to Apple Computer, Inc.
 144 .Pp
 145 The Basic Security Module (BSM) interface to audit records and audit event
 146 stream format were defined by Sun Microsystems.
 147 .Sh BUGS
 148 These routines cannot currently distinguish between an entry not being found
 149 and an error accessing the database.
 150 The implementation should be changed to return an error via
 151 .Va errno
 152 when
 153 .Dv NULL
 154 is returned.