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