syscap_get(2)

NAME
syscap_get, syscap_set - Get and set a capability restriction

LIBRARY
libc

SYNOPSIS
#include <sys/caps.h>
int
syscap_get(int cap, void *data, size_t bytes);
int
syscap_set(int cap, int flags, const void *data, size_t bytes);

DESCRIPTION
The syscap_get() function returns the current flags for the requested capability.

The syscap_set() function add the specified flags to the restrictions applied to a specific capability for the current process. The flags are bitwise ORd into the capability. Capability restrictions cannot be removed once set.

GENERAL
Capability restrictions mostly apply to the root user. Capability restrictions are grouped in sets of 16. Group 0 restrictions also restrict all capabilities in group N. For example, the SYSCAP_RESTRICTEDROOT capability (group 0 capability 1) also restricts all capabilities in group 1.

Capabillities are applied to the current process or its parent process. All threads in a process share the same capabilities.

One can create a relatively (but not completely) secure root environment without jails by combining numerous capability restrictions with a chrooted environment into a filesystem topology constructed from null mounts and tmpfs mounts. The following capabilities are commonly employed when creating such environments: SYSCAP_RESTRICTEDROOT, SYSCAP_SENSITIVEROOT, SYSCAP_NONET_SENSITIVE, SYSCAP_NOVFS_SENSITIVE, SYSCAP_NOMOUNT, and possibly also SYSCAP_NOEXEC_SUID and SYSCAP_NOEXEC_SGID.

GROUP 0 CAPABILITIES (also disable their related sub-groups)

SYSCAP_ANY
    Returns flags that are a wire-or of all other capabilities, indicating that some mucking around with capabilities was done. Generally not explicitly set.

SYSCAP_RESTRICTEDROOT
    Restricts all group 1 capabilities. These are capabililties which most root-run programs should never need to use.

    Most modifying root operations not available as separate capabilities are also restricted by this capability.

SYSCAP_SENSITIVEROOT
    Restrict all group 2 capabilities. These are capabilities that most root-run scripts probably don't need.

SYSCAP_NOEXEC
    Restricts ALL exec*() system calls, including the ones in group 3. However, it is generally not a good idea to prevent execs entirely except in the depths of a well controlled program.

SYSCAP_NOCRED
    Restrict all cred system calls, such as setuid() that are otherwise not generally restricted by RESTRICTEDROOT. These are capabilities that most root run scripts do not need to use unless they are messing around with pty's and terminal emulation.

SYSCAP_NOJAIL
    Restrict all jail related system calls.

SYSCAP_NONET
    Restrict all network related system calls (if you also do NONET_SENSITIVE in addition to this one), generally preventing the use of reserved ports or raw sockets. Note that numerous applications use reserved ports.

SYSCAP_NONET_SENSITIVE
    Restrict all sensitive network related system calls such as ifconfig, packet filter, and other related operations that most programs and scripts do not need to mess with.

SYSCAP_NOVFS
    Restrict all vfs related system calls (if you also do NOVFS_SENSITIVE in addition to this one), generally only allowing basic file open, close, read, and write, and disallowing things like chown, chmod, chroot, and so forth.

SYSCAP_NOVFS_SENSITIVE
    Restrict all sensitive vfs related system calls such as mknod and filesystem control ioctls.

SYSCAP_NOMOUNT
    Restrict all mount and umount operations. This can be combined with a chrooted environment to create secure filesystem topologies. Read-only null mounts are a very powerful tool for creating such environments cheaply.

GROUP 1 CAPABILITIES (ALSO DISABLED BY SYSCAP_RESTRICTEDROOT)

SYSCAP_NODRIVER
    Restrict most driver-related ioctls.

SYSCAP_NOVM_MLOCK
    Restrict mlock() calls.

SYSCAP_NOVM_RESIDENT
    Restrict access to mechanisms which cache already-relocated dynamic binaries in memory.

SYSCAP_NOCPUCTL_WRMSR
    Restrict access to CPUCTL_WRMSR (cpu control registers).

SYSCAP_NOCPUCTL_UPDATE
    Restrict access to CPUCTL_UPDATE (cpu control registers).

SYSCAP_NOACCT
    Restrict access to the acct() system call.

SYSCAP_NOKENV_WR
    Restrict the ability to write to the kernel environment table.

SYSCAP_NOKLD
    Disallow kldload, kldunload, and device firmware loading.

SYSCAP_NOKERN_WR
    Disallow general modifications to kernel space (these are mostly covered by the over-arching RESTRICTEDROOT capability).

SYSCAP_NOREBOOT
    Disallow rebooting and also disallow signaling process 1.

GROUP 2 CAPABILITIES (ALSO DISABLED BY SYSCAP_SENSITIVEROOT)

SYSCAP_NOPROC_TRESPASS
    Do not allow cross-uid process signaling beyond simple uid checks. uid 0 can still signal non-uid-0 processes as long as SYSCAP_RESTRICTEDROOT is active for those processes.

SYSCAP_NOPROC_SETLOGIN
    Disallow use of the setlogin() system call.

SYSCAP_NOPROC_SETRLIMIT
    Do not allow root to raise process resource limits.

SYSCAP_NOSYSCTL_WR
    Do not allow modifying global sysctl() calls.

SYSCAP_NOVARSYM_SYS
    Do not allow modifying system-level varsym operations.

SYSCAP_NOSETHOSTNAME
    Disallow use of the sethostname() system call.

SYSCAP_NOQUOTA_WR
    Disallow use of all modifying filesystem quota operations.

SYSCAP_NODEBUG_UNPRIV
    Do not allow the debugger to be entered via sysctl or root access via procfs.

SYSCAP_NOSETTIME
    Do not allow the system time to be set or adjusted.

SYSCAP_NOSCHED
    Do not allow the system scheduler to be changed, rtprio, or priority raising.

SYSCAP_NOSCHED_CPUSET
    Do not allow the cpuset to be restricted via scheduler calls.

GROUP 3 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOEXEC)

SYSCAP_NOEXEC_SUID
    Do not allow suid execs.

SYSCAP_NOEXEC_SGID
    Do not allow sgid execs.

GROUP 4 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOCRED)

SYSCAP_NOCRED_SETUID

SYSCAP_NOCRED_SETGID

SYSCAP_NOCRED_SETEUID

SYSCAP_NOCRED_SETEGID

SYSCAP_NOCRED_SETREUID

SYSCAP_NOCRED_SETREGID

SYSCAP_NOCRED_SETRESUID

SYSCAP_NOCRED_SETRESGID

SYSCAP_NOCRED_SETGROUPS
    Do not allow various cred related system calls.

GROUP 5 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOJAIL)

SYSCAP_NOJAIL_CREATE
    Do not allow jail creates.

SYSCAP_NOJAIL_ATTACH
    Do not allow jail attachments.

GROUP 6 CAPABILITIES (ALSO DISABLED BY SYSCAP_NONET)

SYSCAP_NONET_RESPORT
    Do not allow ports in the reserved ranges to be bound.

SYSCAP_NONET_RAW
    Do not allow use of raw sockets.

GROUP 7 CAPABILITIES (ALSO DISABLED BY SYSCAP_NONET_SENSITIVE)

SYSCAP_NONET_IFCONFIG
    Do not allow modifications to NICs via ifconfig.

SYSCAP_NONET_ROUTE
    Do not allow modifications to the route table (not implemented yet).

SYSCAP_NONET_LAGG
    Do not allow modifications to LAGG interfaces.

SYSCAP_NONET_NETGRAPH
    Do not allow modifying netgraph operations.

SYSCAP_NONET_BT_RAW
    Do not allow raw bluetooth operations.

SYSCAP_NONET_WIFI
    Do not allow wifi related device ioctls.

GROUP 8 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOVFS)

SYSCAP_NOVFS_SYSFLAGS
    Do not allow chflags on files not owned by the user even if modes or group allow such operations.

SYSCAP_NOVFS_CHOWN
    Do not allow chown operations on files.

SYSCAP_NOVFS_CHMOD
    Do not allow chmod operations on files.

SYSCAP_NOVFS_LINK
    Do not allow hard links.

SYSCAP_NOVFS_CHFLAGS_DEV
    Do not allow chflags on device nodes.

SYSCAP_NOVFS_SETATTR
    If set, prevents most file attribute changes. This should be used only by programs who know for damn sure that none of the library calls they make depend on chflags, chmod(), and other file related functions (obsolete).

SYSCAP_NOVFS_SETGID
    If set, clears SGID during certain file operations in UFS (obsolete).

SYSCAP_NOVFS_GENERATION
    File generation number will be reported as 0 in *stat() calls.

SYSCAP_NOVFS_RETAINSUGID
    If restricted, SUID and SGID bits are cleared when a file is written to. Otherwise normal unix operation is to not clear the bits.

GROUP 9 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOVFS_SENSITIVE)

SYSCAP_NOVFS_MKNOD_BAD
    Do not allow mknod() to create bad entries.

SYSCAP_NOVFS_MKNOD_WHT
    Do not allow mknod() to create whitespace entries.

SYSCAP_NOVFS_MKNOD_DIR
    Do not allow mknod() to create directories.

SYSCAP_NOVFS_MKNOD_DEV
    Do not allow mknod() to create devices.

SYSCAP_NOVFS_IOCTL
    Disallow use of sensitive filesystem related ioctls().

SYSCAP_NOVFS_CHROOT
    Disallow use of the chroot() system call.

SYSCAP_NOVFS_REVOKE
    Disallow use of the revoke() system call.

GROUP 10 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOMOUNT)

SYSCAP_NOMOUNT_NULLFS
    Disallow nullfs mounts.

SYSCAP_NOMOUNT_DEVFS
    Disallow devfs mounts.

SYSCAP_NOMOUNT_TMPFS
    Disallow tmpfs mounts.

SYSCAP_NOMOUNT_UMOUNT
    Disallow unmounts.

SYSCAP_NOMOUNT_FUSE
    Disallow fuse mounts and unmounts.

CAPABILITY DIRECTOR FLAGS (or'd with cap, not the flags)

__SYSCAP_INPARENT
    Adjusts the capability in the parent process of the calling process. If not specified, the capability in the calling process is adjusted. The parent process must be in the same jail and have the same uid.

FLAGS (flags argument)

__SYSCAP_SELF
    A bit mask indicating the restriction is applied to the calling process (or parent process if the capabliity is directed to __SYSCAP_INPARENT ), including process fork()s.

__SYSCAP_EXEC
    A bit mask indicating the restriction is applied to any exec performed by the process. This bit is shifted into the __SYSCAP_SELF bit upon a successful exec*(). The __SYSCAP_EXEC bit is retained so all deeper applications will wind up with both bits set.

__SYSCAP_ALL
    A multi-bit mask that covers both SELF and EXEC

ERRORS
These functions return the current or post-modified capability flags for the specified capability, or returns -1 with errno set as follows.

[EOPNOTSUPP]
    The requested capability does not exist or is not supported.

[EINVAL]
    An invalid parameter was passed. This can be an illegal flag, improper pointer, unsupported structure size, or unsupported content that is not otherwise ignored by the system.

SEE ALSO
syscap_set(2)

HISTORY
The syscap_get() and syscap_set() functions first appeared in DragonFly 6.5.