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.\" $FreeBSD$ 26.\" 27.Dd May 5, 2020 28.Dt CAP_PWD 3 29.Os 30.Sh NAME 31.Nm cap_getpwent , 32.Nm cap_getpwnam , 33.Nm cap_getpwuid , 34.Nm cap_getpwent_r , 35.Nm cap_getpwnam_r , 36.Nm cap_getpwuid_r , 37.Nm cap_setpassent , 38.Nm cap_setpwent , 39.Nm cap_endpwent , 40.Nm cap_pwd_limit_cmds , 41.Nm cap_pwd_limit_fields , 42.Nm cap_pwd_limit_users 43.Nd "library for password database operations in capability mode" 44.Sh LIBRARY 45.Lb libcap_pwd 46.Sh SYNOPSIS 47.In libcasper.h 48.In casper/cap_pwd.h 49.Ft struct passwd * 50.Fn cap_getpwent "cap_channel_t *chan" 51.Ft struct passwd * 52.Fn cap_getpwnam "cap_channel_t *chan" "const char *login" 53.Ft struct passwd * 54.Fn cap_getpwuid "cap_channel_t *chan" "uid_t uid" 55.Ft int 56.Fn cap_getpwent_r "cap_channel_t *chan" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 57.Ft int 58.Fn cap_getpwnam_r "cap_channel_t *chan" "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 59.Ft int 60.Fn cap_getpwuid_r "cap_channel_t *chan" "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 61.Ft int 62.Fn cap_setpassent "cap_channel_t *chan" "int stayopen" 63.Ft void 64.Fn cap_setpwent "cap_channel_t *chan" 65.Ft void 66.Fn cap_endpwent "cap_channel_t *chan" 67.Ft int 68.Fn cap_pwd_limit_cmds "cap_channel_t *chan" "const char * const *cmds" "size_t ncmds" 69.Ft int 70.Fn cap_pwd_limit_fields "cap_channel_t *chan" "const char * const *fields" "size_t nfields" 71.Ft int 72.Fn cap_pwd_limit_users "cap_channel_t *chan" "const char * const *names" "size_t nnames" "uid_t *uids" "size_t nuids" 73.Sh DESCRIPTION 74The functions 75.Fn cap_getpwent , 76.Fn cap_getpwnam , 77.Fn cap_getpwuid , 78.Fn cap_getpwent_r , 79.Fn cap_getpwnam_r , 80.Fn cap_getpwuid_r , 81.Fn cap_setpassent , 82.Fn cap_setpwent , 83and 84.Fn cap_endpwent 85are respectively equivalent to 86.Xr getpwent 3 , 87.Xr getpwnam 3 , 88.Xr getpwuid 3 , 89.Xr getpwent_r 3 , 90.Xr getpwnam_r 3 , 91.Xr getpwuid_r 3 , 92.Xr setpassent 3 , 93.Xr setpwent 3 , 94and 95.Xr cap_endpwent 3 96except that the connection to the 97.Nm system.pwd 98service needs to be provided. 99.Pp 100The 101.Fn cap_pwd_limit_cmds 102function limits the functions allowed in the service. 103The 104.Fa cmds 105variable can be set to 106.Dv getpwent , 107.Dv getpwnam , 108.Dv getpwuid , 109.Dv getpwent_r , 110.Dv getpwnam_r , 111.Dv getpwuid_r , 112.Dv setpassent , 113.Dv setpwent , 114or 115.Dv endpwent 116which will allow to use the function associated with the name. 117The 118.Fa ncmds 119variable contains the number of 120.Fa cmds 121provided. 122.Pp 123The 124.Fn cap_pwd_limit_fields 125function allows limit fields returned in the structure 126.Vt passwd . 127The 128.Fa fields 129variable can be set to 130.Dv pw_name , 131.Dv pw_passwd , 132.Dv pw_uid , 133.Dv pw_gid , 134.Dv pw_change , 135.Dv pw_class , 136.Dv pw_gecos , 137.Dv pw_dir , 138.Dv pw_shell , 139.Dv pw_expire 140or 141.Dv pw_fields 142The field which was set as the limit will be returned, while the rest of the 143values not set this way will have default values. 144The 145.Fa nfields 146variable contains the number of 147.Fa fields 148provided. 149.Pp 150The 151.Fn cap_pwd_limit_users 152function allows to limit access to users. 153The 154.Fa names 155variable allows to limit users by name and the 156.Fa uids 157variable by the user number. 158The 159.Fa nnames 160and 161.Fa nuids 162variables provide numbers of limited names and uids. 163.Sh EXAMPLES 164The following example first opens a capability to casper and then uses this 165capability to create the 166.Nm system.pwd 167casper service and uses it to get a user name. 168.Bd -literal 169cap_channel_t *capcas, *cappwd; 170const char *cmds[] = { "getpwuid" }; 171const char *fields[] = { "pw_name" }; 172uid_t uid[] = { 1 }; 173struct passwd *passwd; 174 175/* Open capability to Casper. */ 176capcas = cap_init(); 177if (capcas == NULL) 178 err(1, "Unable to contact Casper"); 179 180/* Enter capability mode sandbox. */ 181if (cap_enter() < 0 && errno != ENOSYS) 182 err(1, "Unable to enter capability mode"); 183 184/* Use Casper capability to create capability to the system.pwd service. */ 185cappwd = cap_service_open(capcas, "system.pwd"); 186if (cappwd == NULL) 187 err(1, "Unable to open system.pwd service"); 188 189/* Close Casper capability, we don't need it anymore. */ 190cap_close(capcas); 191 192/* Limit service to one single function. */ 193if (cap_pwd_limit_cmds(cappwd, cmds, nitems(cmds))) 194 err(1, "Unable to limit access to system.pwd service"); 195 196/* Limit service to one field as we only need name of the user. */ 197if (cap_pwd_limit_fields(cappwd, fields, nitems(fields))) 198 err(1, "Unable to limit access to system.pwd service"); 199 200/* Limit service to one uid. */ 201if (cap_pwd_limit_users(cappwd, NULL, 0, uid, nitems(uid))) 202 err(1, "Unable to limit access to system.pwd service"); 203 204passwd = cap_getpwuid(cappwd, uid[0]); 205if (passwd == NULL) 206 err(1, "Unable to get name of user"); 207 208printf("UID %d is associated with name %s.\\n", uid[0], passwd->pw_name); 209 210cap_close(cappwd); 211.Ed 212.Sh SEE ALSO 213.Xr cap_enter 2 , 214.Xr endpwent 3 , 215.Xr err 3 , 216.Xr getpwent 3 , 217.Xr getpwent_r 3 , 218.Xr getpwnam 3 , 219.Xr getpwnam_r 3 , 220.Xr getpwuid 3 , 221.Xr getpwuid_r 3 , 222.Xr setpassent 3 , 223.Xr setpwent 3 , 224.Xr capsicum 4 , 225.Xr nv 9 226.Sh HISTORY 227The 228.Nm cap_pwd 229service first appeared in 230.Fx 10.3 . 231.Sh AUTHORS 232The 233.Nm cap_pwd 234service was implemented by 235.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 236under sponsorship from the FreeBSD Foundation. 237.Pp 238This manual page was written by 239.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 240