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