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 October 18, 2007 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 77These functions can be used to check operation credentials and perform 78access control. 79The structure 80.Vt struct puffs_cred 81can contain two types of credentials: ones belonging to users and 82ones belonging to the kernel. 83The latter is further divided into generic kernel credentials and 84file system credentials. 85The general rule is that these should be treated as more powerful 86than superuser credentials, but the file system is free to treat 87them as it sees fit. 88.Ss Credentials 89The 90.Fn puffs_cred_get 91family of functions fetch the uid or gid(s) from the given credential 92cookie. 93They return 0 for success or \-1 for an error and set 94.Va errno . 95An error happens when the credentials represent kernel or file system 96credentials and do not contain an uid or gid(s). 97.Pp 98For 99.Fn puffs_cred_getgroups , 100the argument 101.Fa gids 102should point to an array with room for 103.Fa *ngids 104elements. 105.Pp 106The 107.Fn puffs_cred_is 108family of functions return 1 if the truth value of the function for 109.Fa pcr 110is true and 0 if it is false. 111The function 112.Fn puffs_cred_isjuggernaut 113is true if 114.Fa pcr 115describes superuser, kernel or file system credentials. 116.Ss Access Control 117To help the programmers task of emulating normal kernel file system 118access control semantics, several helper functions are provided to 119check if access is allowed. 120They return 0 if access should be permitted or an errno value to 121indicate that access should be denied with the returned value. 122.Pp 123.Fn puffs_access 124is equivalent to the kernel 125.Fn vaccess 126function. 127The arguments specify current information of the file to be 128tested with the exception of 129.Fa access_mode , 130which is a combination of 131.Dv PUFFS_VREAD , 132.Dv PUFFS_VWRITE 133and 134.Dv PUFFS_VEXEC 135indicating the desired file access mode. 136.Pp 137The rest of the functions provide UFS semantics for operations. 138.Fn puffs_access_chown 139checks if it is permissible to chown a file with the current uid 140and gid to the new uid and gid with the credentials of 141.Fa pcr . 142.Pp 143.Fn puffs_access_chmod 144checks against permission to chmod a file of type 145.Fa type 146to the mode 147.Fa newmode . 148.Pp 149Finally, 150.Fn puffs_access_times 151checks if it is allowable to update the timestamps of a file. 152The argument 153.Fa va_utimes_null 154signals if the flags 155.Dv VA_UTIMES_NULL 156was set in 157.Fa va_vaflags 158of 159.Va struct vattr . 160If coming from a path where this information is unavailable, passing 1610 as this argument restricts the permission of modification to the 162owner and superuser. 163Otherwise the function checks for write permissions to the node and 164returns success if the caller has write permissions. 165.Sh SEE ALSO 166.Xr puffs 3 , 167.Xr vnode 9 168