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