Reference

cap_fileargs(3)

library for handling files in capability mode

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

library “libcap_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_CREAT 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 ⟨[email protected]⟩

BUGS

The cap_fileargs service is considered experimental and should be thoroughly evaluated for risks before deploying in production environments.

History