LIBCAPSICUM(3)						   BSD Library Functions Manual 					    LIBCAPSICUM(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

     library ``libcapsicum''

SYNOPSIS

     #include <libcapsicum.h>
     #include <nv.h>

     cap_channel_t *
     cap_init(void);

     cap_channel_t *
     cap_wrap(int sock);

     int
     cap_unwrap(cap_channel_t *chan);

     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);

     #include <libcapsicum_service.h>

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

DESCRIPTION

     The libcapsicum library allows to manage application capabilities through the casperd(8) daemon.

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

     The cap_init() function opens capability to the casperd(8) daemon.

     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 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.  The exact format depends on the ser-
     vice the capability represents.

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

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

     The cap_xfer_nvlist() function sends the given nvlist, destroys it and receives new nvlist in response over the given capability.	It does
     not matter if the function succeeds or fails, the nvlist 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.

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.

EXAMPLES

     The following example first opens capability to the casperd(8) daemon, then using this capability creates new capability to the system.dns
     casper service and uses the latter capability to resolve IP address.

     cap_channel_t *capcas, *capdns;
     nvlist_t *limits;
     const char *ipstr = "127.0.0.1";
     struct in_addr ip;
     struct hostent *hp;

     /* Open capability to the Casper daemon. */
     capcas = cap_init();
     if (capcas == NULL)
	     err(1, "Unable to contact Casper daemon");

     /* Enter capability mode sandbox. */
     if (cap_enter() < 0 && errno != ENOSYS)
	     err(1, "Unable to enter capability mode");

     /* Use Casper capability to create capability to the system.dns service. */
     capdns = cap_service_open(capcas, "system.dns");
     if (capdns == NULL)
	     err(1, "Unable to open system.dns service");

     /* Close Casper capability, we don't need it anymore. */
     cap_close(capcas);

     /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
     limits = nvlist_create(0);
     nvlist_add_string(limits, "type", "ADDR");
     nvlist_add_number(limits, "family", (uint64_t)AF_INET);
     if (cap_limit_set(capdns, limits) < 0)
	     err(1, "Unable to limit access to the system.dns service");

     /* Convert IP address in C-string to in_addr. */
     if (!inet_aton(ipstr, &ip))
	     errx(1, "Unable to parse IP address %s.", ipstr);

     /* Find hostname for the given IP address. */
     hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
     if (hp == NULL)
	     errx(1, "No name associated with %s.", ipstr);

     printf("Name associated with %s is %s.
", ipstr, hp->h_name);

SEE ALSO

     cap_enter(2), execve(2), kevent(2), poll(2), select(2), cap_gethostbyaddr(3), err(3), gethostbyaddr(3), inet_aton(3), nv(3), capsicum(4),
     unix(4), casperd(8)

AUTHORS

     The libcapsicum library was implemented by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship from the FreeBSD Foundation.

BSD
								  April 14, 2014							       BSD