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 May 5, 2020 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.Sh EXAMPLES 162The following example first opens a capability to casper and then uses this 163capability to create the 164.Nm system.pwd 165casper service and uses it to get a user name. 166.Bd -literal 167cap_channel_t *capcas, *cappwd; 168const char *cmds[] = { "getpwuid" }; 169const char *fields[] = { "pw_name" }; 170uid_t uid[] = { 1 }; 171struct passwd *passwd; 172 173/* Open capability to Casper. */ 174capcas = cap_init(); 175if (capcas == NULL) 176 err(1, "Unable to contact Casper"); 177 178/* Enter capability mode sandbox. */ 179if (cap_enter() < 0 && errno != ENOSYS) 180 err(1, "Unable to enter capability mode"); 181 182/* Use Casper capability to create capability to the system.pwd service. */ 183cappwd = cap_service_open(capcas, "system.pwd"); 184if (cappwd == NULL) 185 err(1, "Unable to open system.pwd service"); 186 187/* Close Casper capability, we don't need it anymore. */ 188cap_close(capcas); 189 190/* Limit service to one single function. */ 191if (cap_pwd_limit_cmds(cappwd, cmds, nitems(cmds))) 192 err(1, "Unable to limit access to system.pwd service"); 193 194/* Limit service to one field as we only need name of the user. */ 195if (cap_pwd_limit_fields(cappwd, fields, nitems(fields))) 196 err(1, "Unable to limit access to system.pwd service"); 197 198/* Limit service to one uid. */ 199if (cap_pwd_limit_users(cappwd, NULL, 0, uid, nitems(uid))) 200 err(1, "Unable to limit access to system.pwd service"); 201 202passwd = cap_getpwuid(cappwd, uid[0]); 203if (passwd == NULL) 204 err(1, "Unable to get name of user"); 205 206printf("UID %d is associated with name %s.\\n", uid[0], passwd->pw_name); 207 208cap_close(cappwd); 209.Ed 210.Sh SEE ALSO 211.Xr cap_enter 2 , 212.Xr endpwent 3 , 213.Xr err 3 , 214.Xr getpwent 3 , 215.Xr getpwent_r 3 , 216.Xr getpwnam 3 , 217.Xr getpwnam_r 3 , 218.Xr getpwuid 3 , 219.Xr getpwuid_r 3 , 220.Xr setpassent 3 , 221.Xr setpwent 3 , 222.Xr capsicum 4 , 223.Xr nv 9 224.Sh HISTORY 225The 226.Nm cap_pwd 227service first appeared in 228.Fx 10.3 . 229.Sh AUTHORS 230The 231.Nm cap_pwd 232service was implemented by 233.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 234under sponsorship from the FreeBSD Foundation. 235.Pp 236This manual page was written by 237.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 238