cap_fileargs.3

.\" Copyright (c) 2018 Mariusz Zaborski <[email protected]>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd August 8, 2025
.Dt CAP_FILEARGS 3
.Os
.Sh NAME
.Nm cap_fileargs ,
.Nm fileargs_cinit ,
.Nm fileargs_cinitnv ,
.Nm fileargs_init ,
.Nm fileargs_initnv ,
.Nm fileargs_free ,
.Nm fileargs_lstat ,
.Nm fileargs_open ,
.Nm fileargs_fopen
.Nd "library for handling files in capability mode"
.Sh SYNOPSIS
.Lb libcap_fileargs
.In sys/nv.h
.In libcasper.h
.In casper/cap_fileargs.h
.Ft "fileargs_t *"
.Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
.Ft "fileargs_t *"
.Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
.Ft "fileargs_t *"
.Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits"
.Ft "fileargs_t *"
.Fn fileargs_initnv "nvlist_t *limits"
.Ft "void"
.Fn fileargs_free "fileargs_t *fa"
.Ft "int"
.Fn fileargs_lstat "fileargs_t *fa" "const char *path" "struct stat *sb"
.Ft "int"
.Fn fileargs_open "fileargs_t *fa" "const char *name"
.Ft "FILE *"
.Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode"
.Ft "char *"
.Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path"
.Sh DESCRIPTION
The
.Nm
library is used to simplify Capsicumizing tools that are using file system.
The idea behind the library is that we pass the remaining arguments from
.Fa argv
(with count specified by
.Fa argc )
which contains the list of files that should be opened by the program.
The library creates a service that will serve those files.
.Pp
The function
.Fn fileargs_init
creates a service to the
.Nm system.fileargs .
The
.Fa argv
contains a list of files that should be opened.
The argument can be set to
.Dv NULL
to create no service and prohibit all files from being opened.
The
.Fa argc
argument contains the number of files passed to the program.
The
.Fa flags
argument specifies whether files can be opened for execution, for reading,
and/or for writing.
The
.Fa mode
argument specifies the permissions to use when creating new files if the
.Dv O_CREAT
flag is set.
For more information about the
.Fa flags
and
.Fa mode
arguments, see
.Xr open 2 .
The
.Fa rightsp
argument specifies the capability rights that will be applied to restrict
access to the files.
For more information about capability rights, see
.Xr cap_rights_init 3 .
The
.Fa operations
argument specifies which operations are permitted when using
.Nm system.fileargs .
The following flags can be combined to form the
.Fa operations
value:
.Bl -ohang -offset indent
.It FA_OPEN
Allow
.Fn fileargs_open
and
.Fn fileargs_fopen .
.It FA_LSTAT
Allow
.Fn fileargs_lstat .
.It FA_REALPATH
Allow
.Fn fileargs_realpath .
.El
.Pp
The function
.Fn fileargs_cinit
behaves identically to
.Fn fileargs_init ,
but requires an existing Casper connection to be passed as an argument.
.Pp
The functions
.Fn fileargs_initnv
and
.Fn fileargs_cinitnv
are equivalent to
.Fn fileargs_init
and
.Fn fileargs_cinit
respectively, but take their arguments in the form of an
.Xr nvlist 9
structure.
See the
.Sx LIMITS
section for details on the expected argument types and values.
.Pp
The
.Fn fileargs_free
function closes the connection to the
.Nm system.fileargs
service and frees all associated data structures.
The function safely handles
.Dv NULL
arguments.
.Pp
The function
.Fn fileargs_lstat
provides the same functionality as
.Xr lstat 2 .
.Pp
The functions
.Fn fileargs_open
and
.Fn fileargs_fopen
behave identically to
.Xr open 2
and
.Xr fopen 3
respectively, but retrieve their arguments from the
.Va fileargs_t
structure.
.Pp
The function
.Fn fileargs_realpath
provides the same functionality as the standard C library function
.Xr realpath 3 ,
resolving all symbolic links and references in a pathname.
.Pp
The following functions are reentrant but require synchronization for
thread safety:
.Fn fileargs_open ,
.Fn fileargs_lstat ,
.Fn fileargs_realpath ,
.Fn fileargs_cinitnv ,
.Fn fileargs_initnv ,
and
.Fn fileargs_fopen .
Multiple threads can call these functions safely only if they use different
.Vt cap_channel_t
arguments or proper synchronization mechanisms.
.Sh LIMITS
This section describes the required and optional arguments that must be
passed to
.Fa system.fileargs
via the
.Fn fileargs_initnv
and
.Fn fileargs_cinitnv
functions using an
.Xr nvlist 9
structure.
.Pp
The following arguments are required:
.Bl -ohang -offset indent
.It flags Pq Dv NV_TYPE_NUMBER
Specifies access permissions for opened files.
.It mode Pq Dv NV_TYPE_NUMBER
Required when the
.Dv O_CREATE
flag is set in
.Va flags .
Specifies the permissions to use when creating new files.
.It operations Pq Dv NV_TYPE_NUMBER
Specifies which operations are allowed for
.Fa system.fileargs .
See the description of the
.Va operations
argument in
.Fn fileargs_init
for possible values.
.El
.Pp
The following arguments are optional in the
.Xr nvlist 9
structure:
.Bl -ohang -offset indent
.It cap_rights Pq Dv NV_TYPE_BINARY
The
.Va cap_rights
argument specifies the capability rights that will be applied to restrict
access to opened files.
.It filenames Pq Dv NV_TYPE_NULL
Multiple
.Dv NV_TYPE_NULL
elements can be provided, where each element's name represents a file
path that is allowed to be opened.
.El
.Sh EXAMPLES
.Bd -literal
int ch, fd, i;
cap_rights_t rights;
fileargs_t *fa;

while ((ch = getopt(argc, argv, "h")) != -1) {
	switch (ch) {
		case 'h':
		default:
			usage();
	}
}

argc -= optind;
argv += optind;

/* Create capability to the system.fileargs service. */
fa = fileargs_init(argc, argv, O_RDONLY, 0,
    cap_rights_init(&rights, CAP_READ), FA_OPEN);
if (fa == NULL)
	err(1, "unable to open system.fileargs service");

/* Enter capability mode sandbox. */
if (cap_enter() < 0 && errno != ENOSYS)
	err(1, "unable to enter capability mode");

/* Open files. */
for (i = 0; i < argc; i++) {
	fd = fileargs_open(fa, argv[i]);
	if (fd < 0)
		err(1, "unable to open file %s", argv[i]);
	printf("File %s opened in capability mode\en", argv[i]);
	close(fd);
}

fileargs_free(fa);
.Ed
.Sh SEE ALSO
.Xr cap_enter 2 ,
.Xr lstat 2 ,
.Xr open 2 ,
.Xr cap_rights_init 3 ,
.Xr err 3 ,
.Xr fopen 3 ,
.Xr getopt 3 ,
.Xr realpath 3 ,
.Xr capsicum 4 ,
.Xr nv 9
.Sh HISTORY
The
.Nm
service first appeared in
.Fx 10.3 .
.Sh AUTHORS
.An Mariusz Zaborski Aq Mt [email protected]
.Sh BUGS
The
.Nm
service is considered experimental and should be thoroughly evaluated
for risks before deploying in production environments.