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 August 8, 2025 26.Dt CAP_FILEARGS 3 27.Os 28.Sh NAME 29.Nm cap_fileargs , 30.Nm fileargs_cinit , 31.Nm fileargs_cinitnv , 32.Nm fileargs_init , 33.Nm fileargs_initnv , 34.Nm fileargs_free , 35.Nm fileargs_lstat , 36.Nm fileargs_open , 37.Nm fileargs_fopen 38.Nd "library for handling files in capability mode" 39.Sh SYNOPSIS 40.Lb libcap_fileargs 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 63The 64.Nm 65library is used to simplify Capsicumizing tools that are using file system. 66The idea behind the library is that we pass the remaining arguments from 67.Fa argv 68(with count specified by 69.Fa argc ) 70which contains the list of files that should be opened by the program. 71The library creates a service that will serve those files. 72.Pp 73The function 74.Fn fileargs_init 75creates 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 82to create no service and prohibit all files from being opened. 83The 84.Fa argc 85argument contains the number of files passed to the program. 86The 87.Fa flags 88argument specifies whether files can be opened for execution, for reading, 89and/or for writing. 90The 91.Fa mode 92argument specifies the permissions to use when creating new files if the 93.Dv O_CREAT 94flag is set. 95For more information about the 96.Fa flags 97and 98.Fa mode 99arguments, see 100.Xr open 2 . 101The 102.Fa rightsp 103argument specifies the capability rights that will be applied to restrict 104access to the files. 105For more information about capability rights, see 106.Xr cap_rights_init 3 . 107The 108.Fa operations 109argument specifies which operations are permitted when using 110.Nm system.fileargs . 111The following flags can be combined to form the 112.Fa operations 113value: 114.Bl -ohang -offset indent 115.It FA_OPEN 116Allow 117.Fn fileargs_open 118and 119.Fn fileargs_fopen . 120.It FA_LSTAT 121Allow 122.Fn fileargs_lstat . 123.It FA_REALPATH 124Allow 125.Fn fileargs_realpath . 126.El 127.Pp 128The function 129.Fn fileargs_cinit 130behaves identically to 131.Fn fileargs_init , 132but requires an existing Casper connection to be passed as an argument. 133.Pp 134The functions 135.Fn fileargs_initnv 136and 137.Fn fileargs_cinitnv 138are equivalent to 139.Fn fileargs_init 140and 141.Fn fileargs_cinit 142respectively, but take their arguments in the form of an 143.Xr nvlist 9 144structure. 145See the 146.Sx LIMITS 147section for details on the expected argument types and values. 148.Pp 149The 150.Fn fileargs_free 151function closes the connection to the 152.Nm system.fileargs 153service and frees all associated data structures. 154The function safely handles 155.Dv NULL 156arguments. 157.Pp 158The function 159.Fn fileargs_lstat 160provides the same functionality as 161.Xr lstat 2 . 162.Pp 163The functions 164.Fn fileargs_open 165and 166.Fn fileargs_fopen 167behave identically to 168.Xr open 2 169and 170.Xr fopen 3 171respectively, but retrieve their arguments from the 172.Va fileargs_t 173structure. 174.Pp 175The function 176.Fn fileargs_realpath 177provides the same functionality as the standard C library function 178.Xr realpath 3 , 179resolving all symbolic links and references in a pathname. 180.Pp 181The following functions are reentrant but require synchronization for 182thread safety: 183.Fn fileargs_open , 184.Fn fileargs_lstat , 185.Fn fileargs_realpath , 186.Fn fileargs_cinitnv , 187.Fn fileargs_initnv , 188and 189.Fn fileargs_fopen . 190Multiple threads can call these functions safely only if they use different 191.Vt cap_channel_t 192arguments or proper synchronization mechanisms. 193.Sh LIMITS 194This section describes the required and optional arguments that must be 195passed to 196.Fa system.fileargs 197via the 198.Fn fileargs_initnv 199and 200.Fn fileargs_cinitnv 201functions using an 202.Xr nvlist 9 203structure. 204.Pp 205The following arguments are required: 206.Bl -ohang -offset indent 207.It flags Pq Dv NV_TYPE_NUMBER 208Specifies access permissions for opened files. 209.It mode Pq Dv NV_TYPE_NUMBER 210Required when the 211.Dv O_CREATE 212flag is set in 213.Va flags . 214Specifies the permissions to use when creating new files. 215.It operations Pq Dv NV_TYPE_NUMBER 216Specifies which operations are allowed for 217.Fa system.fileargs . 218See the description of the 219.Va operations 220argument in 221.Fn fileargs_init 222for possible values. 223.El 224.Pp 225The following arguments are optional in the 226.Xr nvlist 9 227structure: 228.Bl -ohang -offset indent 229.It cap_rights Pq Dv NV_TYPE_BINARY 230The 231.Va cap_rights 232argument specifies the capability rights that will be applied to restrict 233access to opened files. 234.It filenames Pq Dv NV_TYPE_NULL 235Multiple 236.Dv NV_TYPE_NULL 237elements can be provided, where each element's name represents a file 238path that is allowed to be opened. 239.El 240.Sh EXAMPLES 241.Bd -literal 242int ch, fd, i; 243cap_rights_t rights; 244fileargs_t *fa; 245 246while ((ch = getopt(argc, argv, "h")) != -1) { 247 switch (ch) { 248 case 'h': 249 default: 250 usage(); 251 } 252} 253 254argc -= optind; 255argv += optind; 256 257/* Create capability to the system.fileargs service. */ 258fa = fileargs_init(argc, argv, O_RDONLY, 0, 259 cap_rights_init(&rights, CAP_READ), FA_OPEN); 260if (fa == NULL) 261 err(1, "unable to open system.fileargs service"); 262 263/* Enter capability mode sandbox. */ 264if (cap_enter() < 0 && errno != ENOSYS) 265 err(1, "unable to enter capability mode"); 266 267/* Open files. */ 268for (i = 0; i < argc; i++) { 269 fd = fileargs_open(fa, argv[i]); 270 if (fd < 0) 271 err(1, "unable to open file %s", argv[i]); 272 printf("File %s opened in capability mode\en", argv[i]); 273 close(fd); 274} 275 276fileargs_free(fa); 277.Ed 278.Sh SEE ALSO 279.Xr cap_enter 2 , 280.Xr lstat 2 , 281.Xr open 2 , 282.Xr cap_rights_init 3 , 283.Xr err 3 , 284.Xr fopen 3 , 285.Xr getopt 3 , 286.Xr realpath 3 , 287.Xr capsicum 4 , 288.Xr nv 9 289.Sh HISTORY 290The 291.Nm 292service first appeared in 293.Fx 10.3 . 294.Sh AUTHORS 295.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org 296.Sh BUGS 297The 298.Nm 299service is considered experimental and should be thoroughly evaluated 300for risks before deploying in production environments. 301