lib/libc/capability/cap_rights_init.3

   1 .\"
   2 .\" Copyright (c) 2013 The FreeBSD Foundation
   3 .\"
   4 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd May 5, 2020
  29 .Dt CAP_RIGHTS_INIT 3
  30 .Os
  31 .Sh NAME
  32 .Nm cap_rights_init ,
  33 .Nm cap_rights_set ,
  34 .Nm cap_rights_clear ,
  35 .Nm cap_rights_is_set ,
  36 .Nm cap_rights_is_valid ,
  37 .Nm cap_rights_merge ,
  38 .Nm cap_rights_remove ,
  39 .Nm cap_rights_contains
  40 .Nd manage cap_rights_t structure
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/capsicum.h
  45 .Ft cap_rights_t *
  46 .Fn cap_rights_init "cap_rights_t *rights" "..."
  47 .Ft cap_rights_t *
  48 .Fn cap_rights_set "cap_rights_t *rights" "..."
  49 .Ft cap_rights_t *
  50 .Fn cap_rights_clear "cap_rights_t *rights" "..."
  51 .Ft bool
  52 .Fn cap_rights_is_set "const cap_rights_t *rights" "..."
  53 .Ft bool
  54 .Fn cap_rights_is_valid "const cap_rights_t *rights"
  55 .Ft cap_rights_t *
  56 .Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
  57 .Ft cap_rights_t *
  58 .Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
  59 .Ft bool
  60 .Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
  61 .Sh DESCRIPTION
  62 The functions documented here allow to manage the
  63 .Vt cap_rights_t
  64 structure.
  65 .Pp
  66 Capability rights should be separated with comma when passed to the
  67 .Fn cap_rights_init ,
  68 .Fn cap_rights_set ,
  69 .Fn cap_rights_clear
  70 and
  71 .Fn cap_rights_is_set
  72 functions.
  73 For example:
  74 .Bd -literal
  75 cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
  76 .Ed
  77 .Pp
  78 The complete list of the capability rights can be found in the
  79 .Xr rights 4
  80 manual page.
  81 .Pp
  82 The
  83 .Fn cap_rights_init
  84 function initialize provided
  85 .Vt cap_rights_t
  86 structure.
  87 Only properly initialized structure can be passed to the remaining functions.
  88 For convenience the structure can be filled with capability rights instead of
  89 calling the
  90 .Fn cap_rights_set
  91 function later.
  92 For even more convenience pointer to the given structure is returned, so it can
  93 be directly passed to
  94 .Xr cap_rights_limit 2 :
  95 .Bd -literal
  96 cap_rights_t rights;
  97
  98 if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
  99         err(1, "Unable to limit capability rights");
 100 .Ed
 101 .Pp
 102 The
 103 .Fn cap_rights_set
 104 function adds the given capability rights to the given
 105 .Vt cap_rights_t
 106 structure.
 107 .Pp
 108 The
 109 .Fn cap_rights_clear
 110 function removes the given capability rights from the given
 111 .Vt cap_rights_t
 112 structure.
 113 .Pp
 114 The
 115 .Fn cap_rights_is_set
 116 function checks if all the given capability rights are set for the given
 117 .Vt cap_rights_t
 118 structure.
 119 .Pp
 120 The
 121 .Fn cap_rights_is_valid
 122 function verifies if the given
 123 .Vt cap_rights_t
 124 structure is valid.
 125 .Pp
 126 The
 127 .Fn cap_rights_merge
 128 function merges all capability rights present in the
 129 .Fa src
 130 structure into the
 131 .Fa dst
 132 structure.
 133 .Pp
 134 The
 135 .Fn cap_rights_remove
 136 function removes all capability rights present in the
 137 .Fa src
 138 structure from the
 139 .Fa dst
 140 structure.
 141 .Pp
 142 The
 143 .Fn cap_rights_contains
 144 function checks if the
 145 .Fa big
 146 structure contains all capability rights present in the
 147 .Fa little
 148 structure.
 149 .Sh RETURN VALUES
 150 The functions never fail.
 151 In case an invalid capability right or an invalid
 152 .Vt cap_rights_t
 153 structure is given as an argument, the program will be aborted.
 154 .Pp
 155 The
 156 .Fn cap_rights_init ,
 157 .Fn cap_rights_set
 158 and
 159 .Fn cap_rights_clear
 160 functions return pointer to the
 161 .Vt cap_rights_t
 162 structure given in the
 163 .Fa rights
 164 argument.
 165 .Pp
 166 The
 167 .Fn cap_rights_merge
 168 and
 169 .Fn cap_rights_remove
 170 functions return pointer to the
 171 .Vt cap_rights_t
 172 structure given in the
 173 .Fa dst
 174 argument.
 175 .Pp
 176 The
 177 .Fn cap_rights_is_set
 178 returns
 179 .Va true
 180 if all the given capability rights are set in the
 181 .Fa rights
 182 argument.
 183 .Pp
 184 The
 185 .Fn cap_rights_is_valid
 186 function performs various checks to see if the given
 187 .Vt cap_rights_t
 188 structure is valid and returns
 189 .Va true
 190 if it is.
 191 .Pp
 192 The
 193 .Fn cap_rights_contains
 194 function returns
 195 .Va true
 196 if all capability rights set in the
 197 .Fa little
 198 structure are also present in the
 199 .Fa big
 200 structure.
 201 .Sh EXAMPLES
 202 The following example demonstrates how to prepare a
 203 .Vt cap_rights_t
 204 structure to be passed to the
 205 .Xr cap_rights_limit 2
 206 system call.
 207 .Bd -literal
 208 cap_rights_t rights;
 209 int fd;
 210
 211 fd = open("/tmp/foo", O_RDWR);
 212 if (fd < 0)
 213         err(1, "open() failed");
 214
 215 cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
 216
 217 if (allow_write_and_seek)
 218         cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
 219
 220 if (dont_allow_seek)
 221         cap_rights_clear(&rights, CAP_SEEK);
 222
 223 if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
 224         err(1, "cap_rights_limit() failed");
 225 .Ed
 226 .Sh SEE ALSO
 227 .Xr cap_rights_limit 2 ,
 228 .Xr open 2 ,
 229 .Xr capsicum 4 ,
 230 .Xr rights 4
 231 .Sh HISTORY
 232 The functions
 233 .Fn cap_rights_init ,
 234 .Fn cap_rights_set ,
 235 .Fn cap_rights_clear ,
 236 .Fn cap_rights_is_set ,
 237 .Fn cap_rights_is_valid ,
 238 .Fn cap_rights_merge ,
 239 .Fn cap_rights_remove
 240 and
 241 .Fn cap_rights_contains
 242 first appeared in
 243 .Fx 8.3 .
 244 Support for capabilities and capabilities mode was developed as part of the
 245 .Tn TrustedBSD
 246 Project.
 247 .Sh AUTHORS
 248 This family of functions was created by
 249 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 250 under sponsorship from the FreeBSD Foundation.