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

FreeBSD Manual Pages


home | help
CAP_NEW(2)		    BSD	System Calls Manual		    CAP_NEW(2)

     cap_new, cap_getrights -- System calls to manipulate capabilities

     Standard C	Library	(libc, -lc)

     #include <sys/capability.h>

     cap_new(int fd, cap_rights_t rights);

     cap_getrights(int fd, cap_rights_t	*rightsp);

     Capabilities are special file descriptors derived from an existing	file
     descriptor, such as one returned by fhopen(2), kqueue(2), mq_open(2),
     open(2), pipe(2), shm_open(2), socket(2), or socketpair(2), but with a
     restricted	set of permitted operations determined by a rights mask	set
     when the capability is created.  These restricted rights cannot be
     changed after the capability is created, although further capabilities
     with yet more restricted rights may be created from an existing capabil-
     ity.  In every other sense, a capability behaves in the same way as the
     file descriptor it	was created from.

     cap_new() creates a new capability	for the	existing file descriptor fd,
     and returns a file	descriptor for it.  Operations on the capability will
     be	limited	to those permitted by rights, which is static for the lifetime
     of	the capability.	 If fd refers to an existing capability, then rights
     must be equal to or a subset of the rights	on that	capability.  As	with
     dup(2) and	dup2(2), many properties are shared between the	new capability
     and the existing file descriptor, including open file flags, blocking
     disposition, and file offset.  Many applications will prefer to use the
     cap_limitfd(3) library call, part of libcapsicum(3), as it	offers a more
     convenient	interface.

     cap_getrights() queries the rights	associated with	the capability re-
     ferred to by file descriptor fd.

     These system calls, when combined with cap_enter(2), may be used to con-
     struct process sandboxes with highly granular rights assignment.

     The following rights may be specified in a	new capability rights mask:

     CAP_ACCEPT		 Permit	accept(2).

     CAP_ACL_CHECK	 Permit	checking of an ACL on a	file descriptor; there
			 is no cross-reference for this	system call.

     CAP_ACL_DELETE	 Permit	acl_delete_fd_np(3).

     CAP_ACL_GET	 Permit	acl_get_fd(3) and acl_get_fd_np(3).

     CAP_ACL_SET	 Permit	acl_set_fd(3) and acl_set_fd_np(3).

     CAP_BIND		 Permit	bind(2).  Note that sockets can	also become
			 bound implicitly as a result of connect(2) or
			 send(2), and that socket options set with
			 setsockopt(2) may also	affect binding behavior.

     CAP_CONNECT	 Permit	connect(2); also required for sendto(2)	with a
			 non-NULL destination address.

     CAP_EVENT		 Permit	select(2), poll(2), and	kevent(2) to be	used
			 in monitoring the file	descriptor for events.

     CAP_FEXECVE	 Permit	fexecve(2); CAP_READ will also be required.

     CAP_EXTATTR_DELETE	 Permit	extattr_delete_fd(2).

     CAP_EXTATTR_GET	 Permit	extattr_get_fd(2).

     CAP_EXTATTR_LIST	 Permit	extattr_list_fd(2).

     CAP_EXTATTR_SET	 Permit	extattr_set_fd(2).

     CAP_FCHDIR		 Permit	fchdir(2).

     CAP_FCHFLAGS	 Permit	fchflags(2).

     CAP_FCHMOD		 Permit	fchmod(2).

     CAP_FCHOWN		 Permit	fchown(2).

     CAP_FCNTL		 Permit	fcntl(2); be aware that	this call provides in-
			 direct	access to other	operations, such as flock(2).

     CAP_FLOCK		 Permit	flock(2) and related calls.

     CAP_FPATHCONF	 Permit	fpathconf(2).

     CAP_FSCK		 Permit	UFS background-fsck operations on the descrip-

     CAP_FSTAT		 Permit	fstat(2).

     CAP_FSTATFS	 Permit	fstatfs(2).

     CAP_FSYNC		 Permit	aio_fsync(2) and fsync(2).

     CAP_FTRUNCATE	 Permit	ftruncate(2).

     CAP_FUTIMES	 Permit	futimes(2).

     CAP_GETPEERNAME	 Permit	getpeername(2).

     CAP_GETSOCKNAME	 Permit	getsockname(2).

     CAP_GETSOCKOPT	 Permit	getsockopt(2).

     CAP_IOCTL		 Permit	ioctl(2).  Be aware that this system call has
			 enormous scope, including potentially global scope
			 for some objects.

     CAP_KEVENT		 Permit	kevent(2); CAP_EVENT is	also required on file
			 descriptors that will be monitored using kevent(2).

     CAP_LISTEN		 Permit	listen(2); not much use	(generally) without

     CAP_LOOKUP		 Permit	the file descriptor to be used as a starting
			 directory for calls such as linkat(2),	openat(2), and
			 unlinkat(2).  Note that these calls are not available
			 in capability mode as they manipulate a global	name
			 space;	see cap_enter(2) for details.

     CAP_MAC_GET	 Permit	mac_get_fd(3).

     CAP_MAC_SET	 Permit	mac_set_fd(3).

     CAP_MMAP		 Permit	mmap(2); specific invocations may also require

     CAP_PDGETPID	 Permit	pdgetpid(2).

     CAP_PDKILL		 Permit	pdkill(2).

     CAP_PDWAIT		 Permit	pdwait4(2).

     CAP_PEELOFF	 Permit	sctp_peeloff(2).

     CAP_READ		 Allow aio_read(2), pread(2), read(2), recv(2),
			 recvfrom(2), recvmsg(2), and related system calls.

			 For files and other seekable objects, CAP_SEEK	may
			 also be required.

     CAP_REVOKE		 Permit	frevoke(2) in certain ABI compatibility	modes
			 that support this system call.

     CAP_SEEK		 Permit	operations that	seek on	the file descriptor,
			 such as lseek(2), but also required for I/O system
			 calls that modify the file offset, such as read(2)
			 and write(2).

     CAP_SEM_GETVALUE	 Permit	sem_getvalue(3).

     CAP_SEM_POST	 Permit	sem_post(3).

     CAP_SEM_WAIT	 Permit	sem_wait(3) and	sem_trywait(3).

     CAP_SETSOCKOPT	 Permit	setsockopt(2); this controls various aspects
			 of socket behavior and	may affect binding, connect-
			 ing, and other	behaviors with global scope.

     CAP_SHUTDOWN	 Permit	explicit shutdown(2); closing the socket will
			 also generally	shut down any connections on it.

     CAP_TTYHOOK	 Allow configuration of	TTY hooks, such	as snp(4), on
			 the file descriptor.

     CAP_WRITE		 Allow aio_write(2), pwrite(2),	send(2), sendmsg(2),
			 sendto(2), write(2), and related system calls.

			 For files and other seekable objects, CAP_SEEK	may
			 also be required.

			 For sendto(2) with a non-NULL connection address,
			 CAP_CONNECT is	also required.

     The cap_new() system call and the capabilities it creates may be used to
     assign fine-grained rights	to sandboxed processes running in capability
     mode.  However, the semantics of objects accessed via file	descriptors
     are complex, so caution should be exercised in passing object capabili-
     ties into sandboxes.

     If	successful, cap_new() returns a	non-negative integer, termed a file
     descriptor.  It returns -1	on failure, and	sets errno to indicate the er-

     The cap_getrights() function returns the value 0 if successful; otherwise
     the value -1 is returned and the global variable errno is set to indicate
     the error.

     cap_new() may return the following	errors:

     [EBADF]		The fd argument	is not a valid active descriptor.

     [EINVAL]		An invalid right has been requested in rights.

     [EMFILE]		The process has	already	reached	its limit for open
			file descriptors.

     [ENFILE]		The system file	table is full.

     [EPERM]		rights contains	requested rights not present in	the
			current	rights mask associated with the	capability
			referenced by fd, if any.

     cap_getrights() may return	the following errors:

     [EBADF]		The fd argument	is not a valid active descriptor.

     [EINVAL]		The fd argument	is not a capability.

     accept(2),	aio_fsync(2), aio_read(2), aio_write(2), bind(2),
     cap_enter(2), connect(2), dup(2), dup2(2),	extattr_delete_fd(2),
     extattr_get_fd(2),	extattr_list_fd(2), extattr_set_fd(2), fchflags(2),
     fchown(2),	fcntl(2), fexecve(2), fhopen(2), flock(2), fpathconf(2),
     fstat(2), fstatfs(2), fsync(2), ftruncate(2), futimes(2), getpeername(2),
     getsockname(2), getsockopt(2), ioctl(2), kevent(2), kqueue(2), linkat(2),
     listen(2),	mmap(2), mq_open(2), open(2), openat(2), pdgetpid(2),
     pdkill(2),	pdwait4(2), pipe(2), poll(2), pread(2),	pwrite(2), read(2),
     recv(2), recvfrom(2), recvmsg(2), sctp_peeloff(2),	select(2), send(2),
     sendmsg(2), sendto(2), setsockopt(2), shm_open(2),	shutdown(2),
     socket(2),	socketpair(2), unlinkat(2), write(2), acl_delete_fd_np(3),
     acl_get_fd(3), acl_get_fd_np(3), acl_set_fd_np(3),	cap_limitfd(3),
     libcapsicum(3), mac_get_fd(3), mac_set_fd(3), sem_getvalue(3),
     sem_post(3), sem_trywait(3), sem_wait(3), capsicum(4), snp(4)

     Support for capabilities and capabilities mode was	developed as part of
     the TrustedBSD Project.

     These functions and the capability	facility were created by Robert	N. M.
     Watson at the University of Cambridge Computer Laboratory with support
     from a grant from Google, Inc.

     This man page should list the set of permitted system calls more specifi-
     cally for each capability right.

     Capability	rights sometimes have unclear indirect impacts,	which should
     be	documented, or at least	hinted at.

BSD				 July 20, 2011				   BSD


Want to link to this manual page? Use this URL:

home | help