man.bsd.lv manual page server

Manual Page Search Parameters
LIBCASPER(3) Library Functions Manual LIBCASPER(3)

cap_init, cap_wrap, cap_unwrap, cap_sock, cap_clone, cap_close, cap_limit_get, cap_limit_set, cap_send_nvlist, cap_recv_nvlist, cap_xfer_nvlist, cap_service_open — library for handling application capabilities

library “libcasper”

#define WITH_CASPER

#include <sys/nv.h>
#include <libcasper.h>

cap_channel_t *
cap_init(void);

cap_channel_t *
cap_wrap(int sock, int flags);

int
cap_unwrap(cap_channel_t *chan, int *flags);

int
cap_sock(const cap_channel_t *chan);

cap_channel_t *
cap_clone(const cap_channel_t *chan);

void
cap_close(cap_channel_t *chan);

int
cap_limit_get(const cap_channel_t *chan, nvlist_t **limitsp);

int
cap_limit_set(const cap_channel_t *chan, nvlist_t *limits);

int
cap_send_nvlist(const cap_channel_t *chan, const nvlist_t *nvl);

nvlist_t *
cap_recv_nvlist(const cap_channel_t *chan);

nvlist_t *
cap_xfer_nvlist(const cap_channel_t *chan, nvlist_t *nvl);

cap_channel_t *
cap_service_open(const cap_channel_t *chan, const char *name);

The libcasper library allows to manage application capabilities through the casper process.

The application capability (represented by the cap_channel_t type) is a communication channel between the caller and the casper process daemon or an instance of one of its services. A capability to the casper process obtained with the () function allows to create capabilities to casper's services via the cap_service_open() function.

The () function opens capability to the casper process.

The () function creates cap_channel_t based on the given socket. The function is used when capability is inherited through execve(2) or send over unix(4) domain socket as a regular file descriptor and has to be represented as cap_channel_t again. The flags argument defines the channel behavior. The supported flags are:

CASPER_NO_UNIQ
The communication between process and casper uses no unique version of nvlist.

The () function is the opposite of the cap_wrap() function. It frees the cap_channel_t structure and returns unix(4) domain socket associated with it.

The () function clones the given capability.

The () function closes the given capability.

The () function returns unix(4) domain socket descriptor associated with the given capability for use with system calls like kevent(2), poll(2) and select(2).

The () function stores current limits of the given capability in the limitsp argument. If the function return 0 and NULL is stored in limitsp it means there are no limits set.

The () function sets limits for the given capability. The limits are provided as nvlist(9). The exact format depends on the service the capability represents.

The () function sends the given nvlist(9) over the given capability. This is low level interface to communicate with casper services. Most services should provide higher level API.

The () function receives the given nvlist(9) over the given capability.

The () function sends the given nvlist(9), destroys it and receives new nvlist(9) in response over the given capability. It does not matter if the function succeeds or fails, the nvlist(9) given for sending will always be destroyed once the function returns.

The () function opens casper service of the given name through casper capability obtained via the cap_init() function. The function returns capability that provides access to opened service. Casper supports the following services in the base system:

system.dns
provides DNS libc compatible API
system.grp
provides getgrent(3) compatible API
system.pwd
provides getpwent(3) compatible API
system.random
allows to obtain entropy from /dev/random
system.sysctl
provides sysctlbyname(3) compatible API
system.syslog
provides syslog(3) compatible API

The cap_clone(), cap_init(), cap_recv_nvlist(), cap_service_open(), cap_wrap() and cap_xfer_nvlist() functions return NULL and set the errno variable on failure.

The cap_limit_get(), cap_limit_set() and cap_send_nvlist() functions return -1 and set the errno variable on failure.

The cap_close(), cap_sock() and cap_unwrap() functions always succeed.

errno(2), execve(2), kevent(2), poll(2), select(2), cap_dns(3), cap_grp(3), cap_pwd(3), cap_random(3), cap_sysctl(3), cap_syslog(3), libcasper_service(3), capsicum(4), unix(4), nv(9)

The libcasper library was implemented by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship from the FreeBSD Foundation. The libcasper new architecture was implemented by
Mariusz Zaborski <oshogbo@FreeBSD.org>

March 6, 2018 FreeBSD-12.0