.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org>
.\" 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 December 6, 2023
.Dt CAP_FILEARGS 3
.Os
.Sh NAME
.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 LIBRARY
.Lb libcap_fileargs
.Sh SYNOPSIS
.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 library is used to simplify Capsicumizing a tools that are using file system.
Idea behind the library is that we are passing a remaining
.Fa argc
and
.Fa argv
which contains a list of files that should be open for this program.
The library will create a service that will serve those files.
.Pp
The function
.Fn fileargs_init
create 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
which will not create a service and all files will be prohibited to be opened.
The
.Fa argc
argument contains a number of passed files.
The
.Fa flags
argument limits opened files for either execution or reading and/or writing.
The
.Fa mode
argument tells which what mode file should be created if the
.Dv O_CREATE
flag is present .
For more details of the
.Fa flags
and
.Fa mode
arguments see
.Xr open 2 .
The
.Fa rightsp
argument contains a list of the capability rights which file should be limited to.
For more details of the capability rights see
.Xr cap_rights_init 3 .
The
.Fa operations
argument limits the operations that are available using
.Nm system.fileargs .
.Fa operations
is a combination of:
.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
is equivalent to
.Fn fileargs_init
except that the connection to the Casper needs to be provided.
.Pp
The functions
.Fn fileargs_initnv
and
.Fn fileargs_cinitnv
are respectively equivalent to
.Fn fileargs_init
and
.Fn fileargs_cinit
expect that all arguments all provided as
.Xr nvlist 9 .
For details see
.Sx LIMITS .
.Pp
The
.Fa fileargs_free
close connection to the
.Nm system.fileargs
service and free are structures.
The function handle
.Dv NULL
argument.
.Pp
The function
.Fn fileargs_lstat
is equivalent to
.Xr lstat 2 .
.Pp
The functions
.Fn fileargs_open
and
.Fn fileargs_fopen
are respectively equivalent to
.Xr open 2
and
.Xr fopen 3
expect that all arguments are fetched from the
.Va fileargs_t
structure.
.Pp
The function
.Fn fileargs_realpath
is equivalent to
.Xr realpath 3 .
.Pp
.Fn fileargs_open ,
.Fn fileargs_lstat ,
.Fn fileargs_realpath ,
.Fn fileargs_cinitnv ,
.Fn fileargs_initnv ,
and
.Fn fileargs_fopen
are reentrant but not thread-safe.
That is, they may be called from separate threads only with different
.Vt cap_channel_t
arguments or with synchronization.
.Sh LIMITS
This section describe which values and types should be used to pass arguments to the
.Fa system.fileargs
through the
.Fn fileargs_initnv
and
.Fn fileargs_cinitnv
functions.
The
.Xr nvlist 9
for that functions must contain the following values and types:
.Bl -ohang -offset indent
.It flags ( NV_TYPE_NUMBER )
The
.Va flags
limits opened files for either execution or reading and/or writing.
.It mode (NV_TYPE_NUMBER)
If in the
.Va flags
argument the
.Dv O_CREATE
flag was defined the
.Xr nvlist 9
must contain the
.Va mode .
The
.Va mode
argument tells which what mode file should be created.
.It operations (NV_TYPE_NUMBER)
The
.Va operations
limits the usable operations for
.Fa system.fileargs .
The possible values are explained as
.Va operations
argument with
.Fn fileargs_init .
.El
.Pp
The
.Xr nvlist 9
for that functions may contain the following values and types:
.Bl -ohang -offset indent
.It cap_rights ( NV_TYPE_BINARY )
The
.Va cap_rights
argument contains a list of the capability rights which file should be limited to.
.It ( NV_TYPE_NULL )
Any number of
.Dv NV_TYPE_NULL
where the name of the element is name of the file which can be opened.
.El
.Sh EXAMPLES
The following example first parse some options and then create the
.Nm system.fileargs
service with remaining arguments.
.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 cap_fileargs
service first appeared in
.Fx 10.3 .
.Sh AUTHORS
.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
.Sh BUGS
The
.Lb cap_fileargs
included in
.Fx
is considered experimental, and should not be deployed in production
environments without careful consideration of the risks associated with
the use of experimental operating system features.