Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
LIBCASPER(3)		 BSD 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 ca-
     pabilities

LIBRARY
     library "libcasper"

SYNOPSIS
     #include <libcasper.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,	int flags);

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

     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 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 cap_unwrap() function is the opposite of the cap_wrap() function.  It
     frees the cap_channel_t structure and returns unix(4) domain socket asso-
     ciated 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 associ-
     ated 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 capabil-
     ity 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 service
     the capability represents.

     The cap_send_nvlist() function sends the given nvlist over	the given ca-
     pability.	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 flags argument defines what type the top nvlist is ex-
     pected to be.  If the nvlist flags	do not match the flags passed to
     cap_recv_nvlist(),	the nvlist will	not be returned.

     The cap_xfer_nvlist() function sends the given nvlist, destroys it	and
     receives new nvlist in response over the given capability.	 The flags ar-
     gument defines what type the top nvlist is	expected to be.	 If the	nvlist
     flags do not match	the flags passed to cap_xfer_nvlist(), the nvlist will
     not be returned.  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 re-
     turn -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 casper	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. */
     capcas = cap_init();
     if	(capcas	== NULL)
	     err(1, "Unable to contact Casper");

     /*	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.\n",	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)

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>

BSD			       February	25, 2016			   BSD
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libcasper&sektion=3&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help