NAME
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
library “libcasper”
SYNOPSIS
#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);
DESCRIPTION
Thelibcasper 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
cap_init()
function allows to create capabilities to casper's services via the
cap_service_open() function.
The
cap_init()
function opens capability to the casper process.
The
cap_wrap()
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
cap_unwrap()
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
cap_clone()
function clones the given capability.
The
cap_close()
function closes the given capability.
The
cap_sock()
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
cap_limit_get()
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
cap_limit_set()
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
cap_send_nvlist()
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
cap_recv_nvlist()
function receives the given
nvlist(9) over the given capability.
The
cap_xfer_nvlist()
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
cap_service_open()
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
RETURN VALUES
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.
SEE ALSO
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)
AUTHORS
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>