CAP_FILEARGS(3) FreeBSD Library Functions Manual CAP_FILEARGS(3)
NAME
cap_fileargs, fileargs_cinit, fileargs_cinitnv, fileargs_init,
fileargs_initnv, fileargs_free, fileargs_lstat, fileargs_open,
fileargs_fopen - library for handling files in capability mode
SYNOPSIS
/* -lcap_fileargs */
#include <sys/nv.h>
#include <libcasper.h>
#include <casper/cap_fileargs.h>
fileargs_t *
fileargs_init(int argc, char *argv[], int flags, mode_t mode,
cap_rights_t *rightsp, int operations);
fileargs_t *
fileargs_cinit(cap_channel_t *cas, int argc, char *argv[], int flags,
mode_t mode, cap_rights_t *rightsp, int operations);
fileargs_t *
fileargs_cinitnv(cap_channel_t *cas, nvlist_t *limits);
fileargs_t *
fileargs_initnv(nvlist_t *limits);
void
fileargs_free(fileargs_t *fa);
int
fileargs_lstat(fileargs_t *fa, const char *path, struct stat *sb);
int
fileargs_open(fileargs_t *fa, const char *name);
FILE *
fileargs_fopen(fileargs_t *fa, const char *name, const char *mode);
char *
fileargs_realpath(fileargs_t *fa, const char *pathname,
char *reserved_path);
DESCRIPTION
The cap_fileargs 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 argv (with count specified by argc) which
contains the list of files that should be opened by the program. The
library creates a service that will serve those files.
The function fileargs_init() creates a service to the system.fileargs.
The argv contains a list of files that should be opened. The argument
can be set to NULL to create no service and prohibit all files from being
opened. The argc argument contains the number of files passed to the
program. The flags argument specifies whether files can be opened for
execution, for reading, and/or for writing. The mode argument specifies
the permissions to use when creating new files if the O_CREAT flag is
set. For more information about the flags and mode arguments, see
open(2). The rightsp argument specifies the capability rights that will
be applied to restrict access to the files. For more information about
capability rights, see cap_rights_init(3). The operations argument
specifies which operations are permitted when using system.fileargs. The
following flags can be combined to form the operations value:
FA_OPEN
Allow fileargs_open() and fileargs_fopen().
FA_LSTAT
Allow fileargs_lstat().
FA_REALPATH
Allow fileargs_realpath().
The function fileargs_cinit() behaves identically to fileargs_init(), but
requires an existing Casper connection to be passed as an argument.
The functions fileargs_initnv() and fileargs_cinitnv() are equivalent to
fileargs_init() and fileargs_cinit() respectively, but take their
arguments in the form of an nvlist(9) structure. See the LIMITS section
for details on the expected argument types and values.
The fileargs_free() function closes the connection to the system.fileargs
service and frees all associated data structures. The function safely
handles NULL arguments.
The function fileargs_lstat() provides the same functionality as
lstat(2).
The functions fileargs_open() and fileargs_fopen() behave identically to
open(2) and fopen(3) respectively, but retrieve their arguments from the
fileargs_t structure.
The function fileargs_realpath() provides the same functionality as the
standard C library function realpath(3), resolving all symbolic links and
references in a pathname.
The following functions are reentrant but require synchronization for
thread safety: fileargs_open(), fileargs_lstat(), fileargs_realpath(),
fileargs_cinitnv(), fileargs_initnv(), and fileargs_fopen(). Multiple
threads can call these functions safely only if they use different
cap_channel_t arguments or proper synchronization mechanisms.
LIMITS
This section describes the required and optional arguments that must be
passed to system.fileargs via the fileargs_initnv() and
fileargs_cinitnv() functions using an nvlist(9) structure.
The following arguments are required:
flags (NV_TYPE_NUMBER)
Specifies access permissions for opened files.
mode (NV_TYPE_NUMBER)
Required when the O_CREATE flag is set in flags. Specifies the
permissions to use when creating new files.
operations (NV_TYPE_NUMBER)
Specifies which operations are allowed for system.fileargs. See
the description of the operations argument in fileargs_init() for
possible values.
The following arguments are optional in the nvlist(9) structure:
cap_rights (NV_TYPE_BINARY)
The cap_rights argument specifies the capability rights that will
be applied to restrict access to opened files.
filenames (NV_TYPE_NULL)
Multiple NV_TYPE_NULL elements can be provided, where each
element's name represents a file path that is allowed to be opened.
EXAMPLES
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\n", argv[i]);
close(fd);
}
fileargs_free(fa);
SEE ALSO
cap_enter(2), lstat(2), open(2), cap_rights_init(3), err(3), fopen(3),
getopt(3), realpath(3), capsicum(4), nv(9)
HISTORY
The cap_fileargs service first appeared in FreeBSD 10.3.
AUTHORS
Mariusz Zaborski <oshogbo@FreeBSD.org>
BUGS
The cap_fileargs service is considered experimental and should be
thoroughly evaluated for risks before deploying in production
environments.
FreeBSD 15.1-STABLE-HBSD August 8, 2025 CAP_FILEARGS(3)