1.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd December 6, 2023 26.Dt CAP_PWD 3 27.Os 28.Sh NAME 29.Nm cap_getpwent , 30.Nm cap_getpwnam , 31.Nm cap_getpwuid , 32.Nm cap_getpwent_r , 33.Nm cap_getpwnam_r , 34.Nm cap_getpwuid_r , 35.Nm cap_setpassent , 36.Nm cap_setpwent , 37.Nm cap_endpwent , 38.Nm cap_pwd_limit_cmds , 39.Nm cap_pwd_limit_fields , 40.Nm cap_pwd_limit_users 41.Nd "library for password database operations in capability mode" 42.Sh LIBRARY 43.Lb libcap_pwd 44.Sh SYNOPSIS 45.In libcasper.h 46.In casper/cap_pwd.h 47.Ft struct passwd * 48.Fn cap_getpwent "cap_channel_t *chan" 49.Ft struct passwd * 50.Fn cap_getpwnam "cap_channel_t *chan" "const char *login" 51.Ft struct passwd * 52.Fn cap_getpwuid "cap_channel_t *chan" "uid_t uid" 53.Ft int 54.Fn cap_getpwent_r "cap_channel_t *chan" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 55.Ft int 56.Fn cap_getpwnam_r "cap_channel_t *chan" "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 57.Ft int 58.Fn cap_getpwuid_r "cap_channel_t *chan" "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 59.Ft int 60.Fn cap_setpassent "cap_channel_t *chan" "int stayopen" 61.Ft void 62.Fn cap_setpwent "cap_channel_t *chan" 63.Ft void 64.Fn cap_endpwent "cap_channel_t *chan" 65.Ft int 66.Fn cap_pwd_limit_cmds "cap_channel_t *chan" "const char * const *cmds" "size_t ncmds" 67.Ft int 68.Fn cap_pwd_limit_fields "cap_channel_t *chan" "const char * const *fields" "size_t nfields" 69.Ft int 70.Fn cap_pwd_limit_users "cap_channel_t *chan" "const char * const *names" "size_t nnames" "uid_t *uids" "size_t nuids" 71.Sh DESCRIPTION 72The functions 73.Fn cap_getpwent , 74.Fn cap_getpwnam , 75.Fn cap_getpwuid , 76.Fn cap_getpwent_r , 77.Fn cap_getpwnam_r , 78.Fn cap_getpwuid_r , 79.Fn cap_setpassent , 80.Fn cap_setpwent , 81and 82.Fn cap_endpwent 83are respectively equivalent to 84.Xr getpwent 3 , 85.Xr getpwnam 3 , 86.Xr getpwuid 3 , 87.Xr getpwent_r 3 , 88.Xr getpwnam_r 3 , 89.Xr getpwuid_r 3 , 90.Xr setpassent 3 , 91.Xr setpwent 3 , 92and 93.Xr cap_endpwent 3 94except that the connection to the 95.Nm system.pwd 96service needs to be provided. 97.Pp 98The 99.Fn cap_pwd_limit_cmds 100function limits the functions allowed in the service. 101The 102.Fa cmds 103variable can be set to 104.Dv getpwent , 105.Dv getpwnam , 106.Dv getpwuid , 107.Dv getpwent_r , 108.Dv getpwnam_r , 109.Dv getpwuid_r , 110.Dv setpassent , 111.Dv setpwent , 112or 113.Dv endpwent 114which will allow to use the function associated with the name. 115The 116.Fa ncmds 117variable contains the number of 118.Fa cmds 119provided. 120.Pp 121The 122.Fn cap_pwd_limit_fields 123function allows limit fields returned in the structure 124.Vt passwd . 125The 126.Fa fields 127variable can be set to 128.Dv pw_name , 129.Dv pw_passwd , 130.Dv pw_uid , 131.Dv pw_gid , 132.Dv pw_change , 133.Dv pw_class , 134.Dv pw_gecos , 135.Dv pw_dir , 136.Dv pw_shell , 137.Dv pw_expire 138or 139.Dv pw_fields 140The field which was set as the limit will be returned, while the rest of the 141values not set this way will have default values. 142The 143.Fa nfields 144variable contains the number of 145.Fa fields 146provided. 147.Pp 148The 149.Fn cap_pwd_limit_users 150function allows to limit access to users. 151The 152.Fa names 153variable allows to limit users by name and the 154.Fa uids 155variable by the user number. 156The 157.Fa nnames 158and 159.Fa nuids 160variables provide numbers of limited names and uids. 161.Pp 162All of these functions are reentrant but not thread-safe. 163That is, they may be called from separate threads only with different 164.Vt cap_channel_t 165arguments or with synchronization. 166.Sh EXAMPLES 167The following example first opens a capability to casper and then uses this 168capability to create the 169.Nm system.pwd 170casper service and uses it to get a user name. 171.Bd -literal 172cap_channel_t *capcas, *cappwd; 173const char *cmds[] = { "getpwuid" }; 174const char *fields[] = { "pw_name" }; 175uid_t uid[] = { 1 }; 176struct passwd *passwd; 177 178/* Open capability to Casper. */ 179capcas = cap_init(); 180if (capcas == NULL) 181 err(1, "Unable to contact Casper"); 182 183/* Enter capability mode sandbox. */ 184if (cap_enter() < 0 && errno != ENOSYS) 185 err(1, "Unable to enter capability mode"); 186 187/* Use Casper capability to create capability to the system.pwd service. */ 188cappwd = cap_service_open(capcas, "system.pwd"); 189if (cappwd == NULL) 190 err(1, "Unable to open system.pwd service"); 191 192/* Close Casper capability, we don't need it anymore. */ 193cap_close(capcas); 194 195/* Limit service to one single function. */ 196if (cap_pwd_limit_cmds(cappwd, cmds, nitems(cmds))) 197 err(1, "Unable to limit access to system.pwd service"); 198 199/* Limit service to one field as we only need name of the user. */ 200if (cap_pwd_limit_fields(cappwd, fields, nitems(fields))) 201 err(1, "Unable to limit access to system.pwd service"); 202 203/* Limit service to one uid. */ 204if (cap_pwd_limit_users(cappwd, NULL, 0, uid, nitems(uid))) 205 err(1, "Unable to limit access to system.pwd service"); 206 207passwd = cap_getpwuid(cappwd, uid[0]); 208if (passwd == NULL) 209 err(1, "Unable to get name of user"); 210 211printf("UID %d is associated with name %s.\\n", uid[0], passwd->pw_name); 212 213cap_close(cappwd); 214.Ed 215.Sh SEE ALSO 216.Xr cap_enter 2 , 217.Xr endpwent 3 , 218.Xr err 3 , 219.Xr getpwent 3 , 220.Xr getpwent_r 3 , 221.Xr getpwnam 3 , 222.Xr getpwnam_r 3 , 223.Xr getpwuid 3 , 224.Xr getpwuid_r 3 , 225.Xr setpassent 3 , 226.Xr setpwent 3 , 227.Xr capsicum 4 , 228.Xr nv 9 229.Sh HISTORY 230The 231.Nm cap_pwd 232service first appeared in 233.Fx 10.3 . 234.Sh AUTHORS 235The 236.Nm cap_pwd 237service was implemented by 238.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 239under sponsorship from the FreeBSD Foundation. 240.Pp 241This manual page was written by 242.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 243