LIBCASPER(3)           FreeBSD Library Functions Manual           LIBCASPER(3)

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
     Casper Library (libcasper, -lcasper)

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
     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 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 a nvlist(9).  The exact format depends on the
     service the capability represents.  cap_limit_set() frees the limits
     regardless of whether the operation succeeds or fails.

     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.net     provides network libc compatible API
           system.pwd     provides getpwent(3) compatible API
           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_net(3), cap_pwd(3), cap_sysctl(3), cap_syslog(3),
     libcasper_service(3), capsicum(4), unix(4), nv(9)

HISTORY
     The libcasper library first appeared in FreeBSD 10.3.

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>

FreeBSD 13.1-RELEASE-p6         January 3, 2021        FreeBSD 13.1-RELEASE-p6