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 .\" $FreeBSD$
  29 .\"
  30 .Dd May 5, 2020
  31 .Dt CAP_RIGHTS_INIT 3
  32 .Os
  33 .Sh NAME
  34 .Nm cap_rights_init ,
  35 .Nm cap_rights_set ,
  36 .Nm cap_rights_clear ,
  37 .Nm cap_rights_is_set ,
  38 .Nm cap_rights_is_valid ,
  39 .Nm cap_rights_merge ,
  40 .Nm cap_rights_remove ,
  41 .Nm cap_rights_contains
  42 .Nd manage cap_rights_t structure
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/capsicum.h
  47 .Ft cap_rights_t *
  48 .Fn cap_rights_init "cap_rights_t *rights" "..."
  49 .Ft cap_rights_t *
  50 .Fn cap_rights_set "cap_rights_t *rights" "..."
  51 .Ft cap_rights_t *
  52 .Fn cap_rights_clear "cap_rights_t *rights" "..."
  53 .Ft bool
  54 .Fn cap_rights_is_set "const cap_rights_t *rights" "..."
  55 .Ft bool
  56 .Fn cap_rights_is_valid "const cap_rights_t *rights"
  57 .Ft cap_rights_t *
  58 .Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
  59 .Ft cap_rights_t *
  60 .Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
  61 .Ft bool
  62 .Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
  63 .Sh DESCRIPTION
  64 The functions documented here allow to manage the
  65 .Vt cap_rights_t
  66 structure.
  67 .Pp
  68 Capability rights should be separated with comma when passed to the
  69 .Fn cap_rights_init ,
  70 .Fn cap_rights_set ,
  71 .Fn cap_rights_clear
  72 and
  73 .Fn cap_rights_is_set
  74 functions.
  75 For example:
  76 .Bd -literal
  77 cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
  78 .Ed
  79 .Pp
  80 The complete list of the capability rights can be found in the
  81 .Xr rights 4
  82 manual page.
  83 .Pp
  84 The
  85 .Fn cap_rights_init
  86 function initialize provided
  87 .Vt cap_rights_t
  88 structure.
  89 Only properly initialized structure can be passed to the remaining functions.
  90 For convenience the structure can be filled with capability rights instead of
  91 calling the
  92 .Fn cap_rights_set
  93 function later.
  94 For even more convenience pointer to the given structure is returned, so it can
  95 be directly passed to
  96 .Xr cap_rights_limit 2 :
  97 .Bd -literal
  98 cap_rights_t rights;
  99
 100 if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
 101         err(1, "Unable to limit capability rights");
 102 .Ed
 103 .Pp
 104 The
 105 .Fn cap_rights_set
 106 function adds the given capability rights to the given
 107 .Vt cap_rights_t
 108 structure.
 109 .Pp
 110 The
 111 .Fn cap_rights_clear
 112 function removes the given capability rights from the given
 113 .Vt cap_rights_t
 114 structure.
 115 .Pp
 116 The
 117 .Fn cap_rights_is_set
 118 function checks if all the given capability rights are set for the given
 119 .Vt cap_rights_t
 120 structure.
 121 .Pp
 122 The
 123 .Fn cap_rights_is_valid
 124 function verifies if the given
 125 .Vt cap_rights_t
 126 structure is valid.
 127 .Pp
 128 The
 129 .Fn cap_rights_merge
 130 function merges all capability rights present in the
 131 .Fa src
 132 structure into the
 133 .Fa dst
 134 structure.
 135 .Pp
 136 The
 137 .Fn cap_rights_remove
 138 function removes all capability rights present in the
 139 .Fa src
 140 structure from the
 141 .Fa dst
 142 structure.
 143 .Pp
 144 The
 145 .Fn cap_rights_contains
 146 function checks if the
 147 .Fa big
 148 structure contains all capability rights present in the
 149 .Fa little
 150 structure.
 151 .Sh RETURN VALUES
 152 The functions never fail.
 153 In case an invalid capability right or an invalid
 154 .Vt cap_rights_t
 155 structure is given as an argument, the program will be aborted.
 156 .Pp
 157 The
 158 .Fn cap_rights_init ,
 159 .Fn cap_rights_set
 160 and
 161 .Fn cap_rights_clear
 162 functions return pointer to the
 163 .Vt cap_rights_t
 164 structure given in the
 165 .Fa rights
 166 argument.
 167 .Pp
 168 The
 169 .Fn cap_rights_merge
 170 and
 171 .Fn cap_rights_remove
 172 functions return pointer to the
 173 .Vt cap_rights_t
 174 structure given in the
 175 .Fa dst
 176 argument.
 177 .Pp
 178 The
 179 .Fn cap_rights_is_set
 180 returns
 181 .Va true
 182 if all the given capability rights are set in the
 183 .Fa rights
 184 argument.
 185 .Pp
 186 The
 187 .Fn cap_rights_is_valid
 188 function performs various checks to see if the given
 189 .Vt cap_rights_t
 190 structure is valid and returns
 191 .Va true
 192 if it is.
 193 .Pp
 194 The
 195 .Fn cap_rights_contains
 196 function returns
 197 .Va true
 198 if all capability rights set in the
 199 .Fa little
 200 structure are also present in the
 201 .Fa big
 202 structure.
 203 .Sh EXAMPLES
 204 The following example demonstrates how to prepare a
 205 .Vt cap_rights_t
 206 structure to be passed to the
 207 .Xr cap_rights_limit 2
 208 system call.
 209 .Bd -literal
 210 cap_rights_t rights;
 211 int fd;
 212
 213 fd = open("/tmp/foo", O_RDWR);
 214 if (fd < 0)
 215         err(1, "open() failed");
 216
 217 cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
 218
 219 if (allow_write_and_seek)
 220         cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
 221
 222 if (dont_allow_seek)
 223         cap_rights_clear(&rights, CAP_SEEK);
 224
 225 if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
 226         err(1, "cap_rights_limit() failed");
 227 .Ed
 228 .Sh SEE ALSO
 229 .Xr cap_rights_limit 2 ,
 230 .Xr open 2 ,
 231 .Xr capsicum 4 ,
 232 .Xr rights 4
 233 .Sh HISTORY
 234 The functions
 235 .Fn cap_rights_init ,
 236 .Fn cap_rights_set ,
 237 .Fn cap_rights_clear ,
 238 .Fn cap_rights_is_set ,
 239 .Fn cap_rights_is_valid ,
 240 .Fn cap_rights_merge ,
 241 .Fn cap_rights_remove
 242 and
 243 .Fn cap_rights_contains
 244 first appeared in
 245 .Fx 8.3 .
 246 Support for capabilities and capabilities mode was developed as part of the
 247 .Tn TrustedBSD
 248 Project.
 249 .Sh AUTHORS
 250 This family of functions was created by
 251 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 252 under sponsorship from the FreeBSD Foundation.