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.Sh EXAMPLES 226The following example first parse some options and then create the 227.Nm system.fileargs 228service with remaining arguments. 229.Bd -literal 230int ch, fd, i; 231cap_rights_t rights; 232fileargs_t *fa; 233 234while ((ch = getopt(argc, argv, "h")) != -1) { 235 switch (ch) { 236 case 'h': 237 default: 238 usage(); 239 } 240} 241 242argc -= optind; 243argv += optind; 244 245/* Create capability to the system.fileargs service. */ 246fa = fileargs_init(argc, argv, O_RDONLY, 0, 247 cap_rights_init(&rights, CAP_READ), FA_OPEN); 248if (fa == NULL) 249 err(1, "unable to open system.fileargs service"); 250 251/* Enter capability mode sandbox. */ 252if (cap_enter() < 0 && errno != ENOSYS) 253 err(1, "unable to enter capability mode"); 254 255/* Open files. */ 256for (i = 0; i < argc; i++) { 257 fd = fileargs_open(fa, argv[i]); 258 if (fd < 0) 259 err(1, "unable to open file %s", argv[i]); 260 printf("File %s opened in capability mode\en", argv[i]); 261 close(fd); 262} 263 264fileargs_free(fa); 265.Ed 266.Sh SEE ALSO 267.Xr cap_enter 2 , 268.Xr lstat 2 , 269.Xr open 2 , 270.Xr cap_rights_init 3 , 271.Xr err 3 , 272.Xr fopen 3 , 273.Xr getopt 3 , 274.Xr realpath 3 , 275.Xr capsicum 4 , 276.Xr nv 9 277.Sh HISTORY 278The 279.Nm cap_fileargs 280service first appeared in 281.Fx 10.3 . 282.Sh BUGS 283The 284.Lb cap_fileargs 285included in 286.Fx 287is considered experimental, and should not be deployed in production 288environments without careful consideration of the risks associated with 289the use of experimental operating system features. 290.Sh AUTHORS 291.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org 292