lib/libcasper/services/cap_fileargs/cap_fileargs.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 January 10, 2021
  26 .Dt CAP_FILEARGS 3
  27 .Os
  28 .Sh NAME
  29 .Nm fileargs_cinit ,
  30 .Nm fileargs_cinitnv ,
  31 .Nm fileargs_init ,
  32 .Nm fileargs_initnv ,
  33 .Nm fileargs_free ,
  34 .Nm fileargs_lstat ,
  35 .Nm fileargs_open ,
  36 .Nm fileargs_fopen
  37 .Nd "library for handling files in capability mode"
  38 .Sh LIBRARY
  39 .Lb libcap_fileargs
  40 .Sh SYNOPSIS
  41 .In sys/nv.h
  42 .In libcasper.h
  43 .In casper/cap_fileargs.h
  44 .Ft "fileargs_t *"
  45 .Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
  46 .Ft "fileargs_t *"
  47 .Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
  48 .Ft "fileargs_t *"
  49 .Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits"
  50 .Ft "fileargs_t *"
  51 .Fn fileargs_initnv "nvlist_t *limits"
  52 .Ft "void"
  53 .Fn fileargs_free "fileargs_t *fa"
  54 .Ft "int"
  55 .Fn fileargs_lstat "fileargs_t *fa" "const char *path" "struct stat *sb"
  56 .Ft "int"
  57 .Fn fileargs_open "fileargs_t *fa" "const char *name"
  58 .Ft "FILE *"
  59 .Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode"
  60 .Ft "char *"
  61 .Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path"
  62 .Sh DESCRIPTION
  63 The library is used to simplify Capsicumizing a tools that are using file system.
  64 Idea behind the library is that we are passing a remaining
  65 .Fa argc
  66 and
  67 .Fa argv
  68 which contains a list of files that should be open for this program.
  69 The library will create a service that will serve those files.
  70 .Pp
  71 The function
  72 .Fn fileargs_init
  73 create a service to the
  74 .Nm system.fileargs .
  75 The
  76 .Fa argv
  77 contains a list of files that should be opened.
  78 The argument can be set to
  79 .Dv NULL
  80 which will not create a service and all files will be prohibited to be opened.
  81 The
  82 .Fa argc
  83 argument contains a number of passed files.
  84 The
  85 .Fa flags
  86 argument limits opened files for either execution or reading and/or writing.
  87 The
  88 .Fa mode
  89 argument tells which what mode file should be created if the
  90 .Dv O_CREATE
  91 flag is present .
  92 For more details of the
  93 .Fa flags
  94 and
  95 .Fa mode
  96 arguments see
  97 .Xr open 2 .
  98 The
  99 .Fa rightsp
 100 argument contains a list of the capability rights which file should be limited to.
 101 For more details of the capability rights see
 102 .Xr cap_rights_init 3 .
 103 The
 104 .Fa operations
 105 argument limits the operations that are available using
 106 .Nm system.fileargs .
 107 .Fa operations
 108 is a combination of:
 109 .Bl -ohang -offset indent
 110 .It FA_OPEN
 111 Allow
 112 .Fn fileargs_open
 113 and
 114 .Fn fileargs_fopen .
 115 .It FA_LSTAT
 116 Allow
 117 .Fn fileargs_lstat .
 118 .It FA_REALPATH
 119 Allow
 120 .Fn fileargs_realpath .
 121 .El
 122 .Pp
 123 The function
 124 .Fn fileargs_cinit
 125 is equivalent to
 126 .Fn fileargs_init
 127 except that the connection to the Casper needs to be provided.
 128 .Pp
 129 The functions
 130 .Fn fileargs_initnv
 131 and
 132 .Fn fileargs_cinitnv
 133 are respectively equivalent to
 134 .Fn fileargs_init
 135 and
 136 .Fn fileargs_cinit
 137 expect that all arguments all provided as
 138 .Xr nvlist 9 .
 139 For details see
 140 .Sx LIMITS .
 141 .Pp
 142 The
 143 .Fa fileargs_free
 144 close connection to the
 145 .Nm system.fileargs
 146 service and free are structures.
 147 The function handle
 148 .Dv NULL
 149 argument.
 150 .Pp
 151 The function
 152 .Fn fileargs_lstat
 153 is equivalent to
 154 .Xr lstat 2 .
 155 .Pp
 156 The functions
 157 .Fn fileargs_open
 158 and
 159 .Fn fileargs_fopen
 160 are respectively equivalent to
 161 .Xr open 2
 162 and
 163 .Xr fopen 3
 164 expect that all arguments are fetched from the
 165 .Va fileargs_t
 166 structure.
 167 .Pp
 168 The function
 169 .Fn fileargs_realpath
 170 is equivalent to
 171 .Xr realpath 3 .
 172 .Sh LIMITS
 173 This section describe which values and types should be used to pass arguments to the
 174 .Fa system.fileargs
 175 through the
 176 .Fn fileargs_initnv
 177 and
 178 .Fn fileargs_cinitnv
 179 functions.
 180 The
 181 .Xr nvlist 9
 182 for that functions must contain the following values and types:
 183 .Bl -ohang -offset indent
 184 .It flags ( NV_TYPE_NUMBER )
 185 The
 186 .Va flags
 187 limits opened files for either execution or reading and/or writing.
 188 .It mode (NV_TYPE_NUMBER)
 189 If in the
 190 .Va flags
 191 argument the
 192 .Dv O_CREATE
 193 flag was defined the
 194 .Xr nvlist 9
 195 must contain the
 196 .Va mode .
 197 The
 198 .Va mode
 199 argument tells which what mode file should be created.
 200 .It operations (NV_TYPE_NUMBER)
 201 The
 202 .Va operations
 203 limits the usable operations for
 204 .Fa system.fileargs .
 205 The possible values are explained as
 206 .Va operations
 207 argument with
 208 .Fn fileargs_init .
 209 .El
 210 .Pp
 211 The
 212 .Xr nvlist 9
 213 for that functions may contain the following values and types:
 214 .Bl -ohang -offset indent
 215 .It cap_rights ( NV_TYPE_BINARY )
 216 The
 217 .Va cap_rights
 218 argument contains a list of the capability rights which file should be limited to.
 219 .It ( NV_TYPE_NULL )
 220 Any number of
 221 .Dv NV_TYPE_NULL
 222 where the name of the element is name of the file which can be opened.
 223 .El
 224 .Sh EXAMPLES
 225 The following example first parse some options and then create the
 226 .Nm system.fileargs
 227 service with remaining arguments.
 228 .Bd -literal
 229 int ch, fd, i;
 230 cap_rights_t rights;
 231 fileargs_t *fa;
 232
 233 while ((ch = getopt(argc, argv, "h")) != -1) {
 234         switch (ch) {
 235                 case 'h':
 236                 default:
 237                         usage();
 238         }
 239 }
 240
 241 argc -= optind;
 242 argv += optind;
 243
 244 /* Create capability to the system.fileargs service. */
 245 fa = fileargs_init(argc, argv, O_RDONLY, 0,
 246     cap_rights_init(&rights, CAP_READ), FA_OPEN);
 247 if (fa == NULL)
 248         err(1, "unable to open system.fileargs service");
 249
 250 /* Enter capability mode sandbox. */
 251 if (cap_enter() < 0 && errno != ENOSYS)
 252         err(1, "unable to enter capability mode");
 253
 254 /* Open files. */
 255 for (i = 0; i < argc; i++) {
 256         fd = fileargs_open(fa, argv[i]);
 257         if (fd < 0)
 258                 err(1, "unable to open file %s", argv[i]);
 259         printf("File %s opened in capability mode\en", argv[i]);
 260         close(fd);
 261 }
 262
 263 fileargs_free(fa);
 264 .Ed
 265 .Sh SEE ALSO
 266 .Xr cap_enter 2 ,
 267 .Xr lstat 2 ,
 268 .Xr open 2 ,
 269 .Xr cap_rights_init 3 ,
 270 .Xr err 3 ,
 271 .Xr fopen 3 ,
 272 .Xr getopt 3 ,
 273 .Xr realpath 3 ,
 274 .Xr capsicum 4 ,
 275 .Xr nv 9
 276 .Sh HISTORY
 277 The
 278 .Nm cap_fileargs
 279 service first appeared in
 280 .Fx 10.3 .
 281 .Sh AUTHORS
 282 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 283 .Sh BUGS
 284 The
 285 .Lb cap_fileargs
 286 included in
 287 .Fx
 288 is considered experimental, and should not be deployed in production
 289 environments without careful consideration of the risks associated with
 290 the use of experimental operating system features.