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_GRP 3 27.Os 28.Sh NAME 29.Nm cap_getgrent , 30.Nm cap_getgrnam , 31.Nm cap_getgrgid , 32.Nm cap_getgrent_r , 33.Nm cap_getgrnam_r , 34.Nm cap_getgrgid_r , 35.Nm cap_setgroupent , 36.Nm cap_setgrent , 37.Nm cap_endgrent , 38.Nm cap_grp_limit_cmds , 39.Nm cap_grp_limit_fields , 40.Nm cap_grp_limit_groups 41.Nd "library for group database operations in capability mode" 42.Sh LIBRARY 43.Lb libcap_grp 44.Sh SYNOPSIS 45.In sys/nv.h 46.In libcasper.h 47.In casper/cap_grp.h 48.Ft "struct group *" 49.Fn cap_getgrent "cap_channel_t *chan" 50.Ft "struct group *" 51.Fn cap_getgrnam "cap_channel_t *chan" "const char *name" 52.Ft "struct group *" 53.Fn cap_getgrgid "cap_channel_t *chan" "gid_t gid" 54.Ft "int" 55.Fn cap_getgrent_r "cap_channel_t *chan" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 56.Ft "int" 57.Fn cap_getgrnam_r "cap_channel_t *chan" "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 58.Ft int 59.Fn cap_getgrgid_r "cap_channel_t *chan" "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" 60.Ft int 61.Fn cap_setgroupent "cap_channel_t *chan" "int stayopen" 62.Ft int 63.Fn cap_setgrent "cap_channel_t *chan" 64.Ft void 65.Fn cap_endgrent "cap_channel_t *chan" 66.Ft int 67.Fn cap_grp_limit_cmds "cap_channel_t *chan" "const char * const *cmds" "size_t ncmds" 68.Ft int 69.Fn cap_grp_limit_fields "cap_channel_t *chan" "const char * const *fields" "size_t nfields" 70.Ft int 71.Fn cap_grp_limit_groups "cap_channel_t *chan" "const char * const *names" "size_t nnames" "const gid_t *gids" "size_t ngids" 72.Sh DESCRIPTION 73The functions 74.Fn cap_getgrent , 75.Fn cap_getgrnam , 76.Fn cap_getgrgid , 77.Fn cap_getgrent_r , 78.Fn cap_getgrnam_r , 79.Fn cap_getgrgid_r , 80.Fn cap_setgroupent , 81.Fn cap_setgrent , 82and 83.Fn cap_endgrent 84are respectively equivalent to 85.Xr getgrent 3 , 86.Xr getgrnam 3 , 87.Xr getgrgid 3 , 88.Xr getgrent_r 3 , 89.Xr getgrnam_r 3 , 90.Xr getgrgid_r 3 , 91.Xr setgroupent 3 , 92.Xr setgrent 3 , 93and 94.Xr endgrent 3 95except that the connection to the 96.Nm system.grp 97service needs to be provided. 98.Pp 99The 100.Fn cap_grp_limit_cmds 101function limits the functions allowed in the service. 102The 103.Fa cmds 104variable can be set to 105.Dv getgrent , 106.Dv getgrnam , 107.Dv getgrgid , 108.Dv getgrent_r , 109.Dv getgrnam_r , 110.Dv getgrgid_r , 111.Dv setgroupent , 112.Dv setgrent , 113or 114.Dv endgrent 115which will allow to use the function associated with the name. 116The 117.Fa ncmds 118variable contains the number of 119.Fa cmds 120provided. 121.Pp 122The 123.Fn cap_grp_limit_fields 124function allows limit fields returned in the structure 125.Vt group . 126The 127.Fa fields 128variable can be set to 129.Dv gr_name 130.Dv gr_passwd 131.Dv gr_gid 132or 133.Dv gr_mem . 134The field which was set as the limit will be returned, while the rest of the 135values not set this way will have default values. 136The 137.Fa nfields 138variable contains the number of 139.Fa fields 140provided. 141.Pp 142The 143.Fn cap_grp_limit_groups 144function allows to limit access to groups. 145The 146.Fa names 147variable allows to limit groups by name and the 148.Fa gids 149variable by the group number. 150The 151.Fa nnames 152and 153.Fa ngids 154variables provide numbers of limited names and gids. 155.Pp 156All of these functions are reentrant but not thread-safe. 157That is, they may be called from separate threads only with different 158.Vt cap_channel_t 159arguments or with synchronization. 160.Sh EXAMPLES 161The following example first opens a capability to casper and then uses this 162capability to create the 163.Nm system.grp 164casper service and uses it to get a group name. 165.Bd -literal 166cap_channel_t *capcas, *capgrp; 167const char *cmds[] = { "getgrgid" }; 168const char *fields[] = { "gr_name" }; 169const gid_t gid[] = { 1 }; 170struct group *group; 171 172/* Open capability to Casper. */ 173capcas = cap_init(); 174if (capcas == NULL) 175 err(1, "Unable to contact Casper"); 176 177/* Enter capability mode sandbox. */ 178if (cap_enter() < 0 && errno != ENOSYS) 179 err(1, "Unable to enter capability mode"); 180 181/* Use Casper capability to create capability to the system.grp service. */ 182capgrp = cap_service_open(capcas, "system.grp"); 183if (capgrp == NULL) 184 err(1, "Unable to open system.grp service"); 185 186/* Close Casper capability, we don't need it anymore. */ 187cap_close(capcas); 188 189/* Limit service to one single function. */ 190if (cap_grp_limit_cmds(capgrp, cmds, nitems(cmds))) 191 err(1, "Unable to limit access to system.grp service"); 192 193/* Limit service to one field as we only need name of the group. */ 194if (cap_grp_limit_fields(capgrp, fields, nitems(fields))) 195 err(1, "Unable to limit access to system.grp service"); 196 197/* Limit service to one gid. */ 198if (cap_grp_limit_groups(capgrp, NULL, 0, gid, nitems(gid))) 199 err(1, "Unable to limit access to system.grp service"); 200 201group = cap_getgrgid(capgrp, gid[0]); 202if (group == NULL) 203 err(1, "Unable to get name of group"); 204 205printf("GID %d is associated with name %s.\\n", gid[0], group->gr_name); 206 207cap_close(capgrp); 208.Ed 209.Sh SEE ALSO 210.Xr cap_enter 2 , 211.Xr endgrent 3 , 212.Xr err 3 , 213.Xr getgrent 3 , 214.Xr getgrent_r 3 , 215.Xr getgrgid 3 , 216.Xr getgrgid_r 3 , 217.Xr getgrnam 3 , 218.Xr getgrnam_r 3 , 219.Xr setgrent 3 , 220.Xr setgroupent 3 , 221.Xr capsicum 4 , 222.Xr nv 9 223.Sh HISTORY 224The 225.Nm cap_grp 226service first appeared in 227.Fx 10.3 . 228.Sh AUTHORS 229The 230.Nm cap_grp 231service was implemented by 232.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 233under sponsorship from the FreeBSD Foundation. 234.Pp 235This manual page was written by 236.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 237