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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
CAP_NEW(2)                FreeBSD System Calls Manual               CAP_NEW(2)

NAME
     cap_new, cap_getrights - System calls to manipulate capabilities

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/capability.h>

     int
     cap_new(int fd, cap_rights_t rights);

     int
     cap_getrights(int fd, cap_rights_t *rightsp);

DESCRIPTION
     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
     capability.  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
     referred to by file descriptor fd.

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

RIGHTS
     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
                         indirect 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
                         descriptor.

     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_BIND.

     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_READ or CAP_WRITE.

     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,
                         connecting, 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.

CAVEAT
     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
     capabilities into sandboxes.

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

     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.

ERRORS
     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.

SEE ALSO
     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)

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

AUTHORS
     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.

BUGS
     This man page should list the set of permitted system calls more
     specifically for each capability right.

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

FreeBSD 11.0-PRERELEASE          July 20, 2011         FreeBSD 11.0-PRERELEASE

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RIGHTS | CAVEAT | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cap_new&sektion=2&manpath=FreeBSD+9.2-RELEASE>

home | help