lib/libpuffs/puffs_cred.3

   1 .\"     $NetBSD: puffs_cred.3,v 1.5 2009/04/11 15:36:22 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 2007 Antti Kantee.  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 February 5, 2012
  27 .Dt PUFFS_CRED 3
  28 .Os
  29 .Sh NAME
  30 .Nm puffs_cred
  31 .Nd puffs credential and access control routines
  32 .Sh LIBRARY
  33 .Lb libpuffs
  34 .Sh SYNOPSIS
  35 .In puffs.h
  36 .Ft int
  37 .Fn puffs_cred_getuid "const struct puffs_cred *pcr" "uid_t *uid"
  38 .Ft int
  39 .Fn puffs_cred_getgid "const struct puffs_cred *pcr" "gid_t *gid"
  40 .Ft int
  41 .Fo puffs_cred_getgroups
  42 .Fa "const struct puffs_cred *pcr" "gid_t *gids" "short *ngids"
  43 .Fc
  44 .Pp
  45 .Ft bool
  46 .Fn puffs_cred_isuid "const struct puffs_cred *pcr" "uid_t uid"
  47 .Ft bool
  48 .Fn puffs_cred_hasgroup "const struct puffs_cred *pcr" "gid_t gid"
  49 .Ft bool
  50 .Fn puffs_cred_iskernel "const struct puffs_cred *pcr"
  51 .Ft bool
  52 .Fn puffs_cred_isfs "const struct puffs_cred *pcr"
  53 .Ft bool
  54 .Fn puffs_cred_isjuggernaut "const struct puffs_cred *pcr"
  55 .Pp
  56 .Ft int
  57 .Fo puffs_access
  58 .Fa "enum vtype type" "mode_t file_mode" "uid_t owner" "gid_t group"
  59 .Fa "mode_t access_mode" "const struct puffs_cred *pcr"
  60 .Fc
  61 .Ft int
  62 .Fo puffs_access_chown
  63 .Fa "uid_t owner" "gid_t group" "uid_t newowner" "gid_t newgroup"
  64 .Fa "const struct puffs_cred *pcr"
  65 .Fc
  66 .Ft int
  67 .Fo puffs_access_chmod
  68 .Fa "uid_t owner" "gid_t group" "enum vtype type" "mode_t newmode"
  69 .Fa "const struct puffs_cred *pcr"
  70 .Fc
  71 .Ft int
  72 .Fo puffs_access_times
  73 .Fa "uid_t owner" "gid_t group" "mode_t file_mode" "int va_utimes_null"
  74 .Fa "const struct puffs_cred *pcr"
  75 .Fc
  76 .Sh DESCRIPTION
  77 These functions can be used to check operation credentials and perform
  78 access control.
  79 The structure
  80 .Vt struct puffs_cred
  81 can contain two types of credentials: ones belonging to users and
  82 ones belonging to the kernel.
  83 The latter is further divided into generic kernel credentials and
  84 file system credentials.
  85 The general rule is that these should be treated as more powerful
  86 than superuser credentials, but the file system is free to treat
  87 them as it sees fit.
  88 .Ss Credentials
  89 The
  90 .Fn puffs_cred_get
  91 family of functions fetch the uid or gid(s) from the given credential
  92 cookie.
  93 They return 0 for success or \-1 for an error and set
  94 .Va errno .
  95 An error happens when the credentials represent kernel or file system
  96 credentials and do not contain an uid or gid(s).
  97 .Pp
  98 For
  99 .Fn puffs_cred_getgroups ,
 100 the argument
 101 .Fa gids
 102 should point to an array with room for
 103 .Fa *ngids
 104 elements.
 105 .Pp
 106 The
 107 .Fn puffs_cred_is
 108 family of functions return 1 if the truth value of the function for
 109 .Fa pcr
 110 is true and 0 if it is false.
 111 The function
 112 .Fn puffs_cred_isjuggernaut
 113 is true if
 114 .Fa pcr
 115 describes superuser, kernel or file system credentials.
 116 .Ss Access Control
 117 To help the programmers task of emulating normal kernel file system
 118 access control semantics, several helper functions are provided to
 119 check if access is allowed.
 120 They return 0 if access should be permitted or an errno value to
 121 indicate that access should be denied with the returned value.
 122 .Pp
 123 .Fn puffs_access
 124 is equivalent to the kernel
 125 .Fn vaccess
 126 function.
 127 The arguments specify current information of the file to be
 128 tested with the exception of
 129 .Fa access_mode ,
 130 which is a combination of
 131 .Dv PUFFS_VREAD ,
 132 .Dv PUFFS_VWRITE
 133 and
 134 .Dv PUFFS_VEXEC
 135 indicating the desired file access mode.
 136 .Pp
 137 The rest of the functions provide UFS semantics for operations.
 138 .Fn puffs_access_chown
 139 checks if it is permissible to chown a file with the current uid
 140 and gid to the new uid and gid with the credentials of
 141 .Fa pcr .
 142 .Pp
 143 .Fn puffs_access_chmod
 144 checks against permission to chmod a file of type
 145 .Fa type
 146 to the mode
 147 .Fa newmode .
 148 .Pp
 149 Finally,
 150 .Fn puffs_access_times
 151 checks if it is allowable to update the timestamps of a file.
 152 The argument
 153 .Fa va_utimes_null
 154 signals if the flags
 155 .Dv VA_UTIMES_NULL
 156 was set in
 157 .Fa va_vaflags
 158 of
 159 .Va struct vattr .
 160 If coming from a path where this information is unavailable, passing
 161 0 as this argument restricts the permission of modification to the
 162 owner and superuser.
 163 Otherwise the function checks for write permissions to the node and
 164 returns success if the caller has write permissions.
 165 .Sh SEE ALSO
 166 .Xr puffs 3 ,
 167 .Xr vnode 9