lib/libc/capability/cap_rights_init.3

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