lib/libcasper/services/cap_grp/cap_grp.3

   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
  73 The 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 ,
  82 and
  83 .Fn cap_endgrent
  84 are 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 ,
  93 and
  94 .Xr endgrent 3
  95 except that the connection to the
  96 .Nm system.grp
  97 service needs to be provided.
  98 .Pp
  99 The
 100 .Fn cap_grp_limit_cmds
 101 function limits the functions allowed in the service.
 102 The
 103 .Fa cmds
 104 variable 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 ,
 113 or
 114 .Dv endgrent
 115 which will allow to use the function associated with the name.
 116 The
 117 .Fa ncmds
 118 variable contains the number of
 119 .Fa cmds
 120 provided.
 121 .Pp
 122 The
 123 .Fn cap_grp_limit_fields
 124 function allows limit fields returned in the structure
 125 .Vt group .
 126 The
 127 .Fa fields
 128 variable can be set to
 129 .Dv gr_name
 130 .Dv gr_passwd
 131 .Dv gr_gid
 132 or
 133 .Dv gr_mem .
 134 The field which was set as the limit will be returned, while the rest of the
 135 values not set this way will have default values.
 136 The
 137 .Fa nfields
 138 variable contains the number of
 139 .Fa fields
 140 provided.
 141 .Pp
 142 The
 143 .Fn cap_grp_limit_groups
 144 function allows to limit access to groups.
 145 The
 146 .Fa names
 147 variable allows to limit groups by name and the
 148 .Fa gids
 149 variable by the group number.
 150 The
 151 .Fa nnames
 152 and
 153 .Fa ngids
 154 variables provide numbers of limited names and gids.
 155 .Sh EXAMPLES
 156 The following example first opens a capability to casper and then uses this
 157 capability to create the
 158 .Nm system.grp
 159 casper service and uses it to get a group name.
 160 .Bd -literal
 161 cap_channel_t *capcas, *capgrp;
 162 const char *cmds[] = { "getgrgid" };
 163 const char *fields[] = { "gr_name" };
 164 const gid_t gid[] = { 1 };
 165 struct group *group;
 166
 167 /* Open capability to Casper. */
 168 capcas = cap_init();
 169 if (capcas == NULL)
 170         err(1, "Unable to contact Casper");
 171
 172 /* Enter capability mode sandbox. */
 173 if (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. */
 177 capgrp = cap_service_open(capcas, "system.grp");
 178 if (capgrp == NULL)
 179         err(1, "Unable to open system.grp service");
 180
 181 /* Close Casper capability, we don't need it anymore. */
 182 cap_close(capcas);
 183
 184 /* Limit service to one single function. */
 185 if (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. */
 189 if (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. */
 193 if (cap_grp_limit_groups(capgrp, NULL, 0, gid, nitems(gid)))
 194         err(1, "Unable to limit access to system.grp service");
 195
 196 group = cap_getgrgid(capgrp, gid[0]);
 197 if (group == NULL)
 198         err(1, "Unable to get name of group");
 199
 200 printf("GID %d is associated with name %s.\\n", gid[0], group->gr_name);
 201
 202 cap_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
 219 The
 220 .Nm cap_grp
 221 service first appeared in
 222 .Fx 10.3 .
 223 .Sh AUTHORS
 224 The
 225 .Nm cap_grp
 226 service was implemented by
 227 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 228 under sponsorship from the FreeBSD Foundation.
 229 .Pp
 230 This manual page was written by
 231 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org .