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