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_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.Sh EXAMPLES 156The following example first opens a capability to casper and then uses this 157capability to create the 158.Nm system.grp 159casper service and uses it to get a group name. 160.Bd -literal 161cap_channel_t *capcas, *capgrp; 162const char *cmds[] = { "getgrgid" }; 163const char *fields[] = { "gr_name" }; 164const gid_t gid[] = { 1 }; 165struct group *group; 166 167/* Open capability to Casper. */ 168capcas = cap_init(); 169if (capcas == NULL) 170 err(1, "Unable to contact Casper"); 171 172/* Enter capability mode sandbox. */ 173if (cap_enter() < 0 && errno != ENOSYS) 174 err(1, "Unable to enter capability mode"); 175 176/* Use Casper capability to create capability to the system.grp service. */ 177capgrp = cap_service_open(capcas, "system.grp"); 178if (capgrp == NULL) 179 err(1, "Unable to open system.grp service"); 180 181/* Close Casper capability, we don't need it anymore. */ 182cap_close(capcas); 183 184/* Limit service to one single function. */ 185if (cap_grp_limit_cmds(capgrp, cmds, nitems(cmds))) 186 err(1, "Unable to limit access to system.grp service"); 187 188/* Limit service to one field as we only need name of the group. */ 189if (cap_grp_limit_fields(capgrp, fields, nitems(fields))) 190 err(1, "Unable to limit access to system.grp service"); 191 192/* Limit service to one gid. */ 193if (cap_grp_limit_groups(capgrp, NULL, 0, gid, nitems(gid))) 194 err(1, "Unable to limit access to system.grp service"); 195 196group = cap_getgrgid(capgrp, gid[0]); 197if (group == NULL) 198 err(1, "Unable to get name of group"); 199 200printf("GID %d is associated with name %s.\\n", gid[0], group->gr_name); 201 202cap_close(capgrp); 203.Ed 204.Sh SEE ALSO 205.Xr cap_enter 2 , 206.Xr endgrent 3 , 207.Xr err 3 , 208.Xr getgrent 3 , 209.Xr getgrent_r 3 , 210.Xr getgrgid 3 , 211.Xr getgrgid_r 3 , 212.Xr getgrnam 3 , 213.Xr getgrnam_r 3 , 214.Xr setgrent 3 , 215.Xr setgroupent 3 , 216.Xr capsicum 4 , 217.Xr nv 9 218.Sh HISTORY 219The 220.Nm cap_grp 221service first appeared in 222.Fx 10.3 . 223.Sh AUTHORS 224The 225.Nm cap_grp 226service was implemented by 227.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 228under sponsorship from the FreeBSD Foundation. 229.Pp 230This manual page was written by 231.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 232