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