1.\" Copyright (c) 2023 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Matthew Dillon <dillon@backplane.com> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd October 11, 2023 34.Dt syscap_get 2 35.Os 36.Sh NAME 37.Nm syscap_get , 38.Nm syscap_set 39.Nd Get and set a capability restriction 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/caps.h 44.Ft int 45.Fn syscap_get "int cap" "void *data" "size_t bytes" 46.Ft int 47.Fn syscap_set "int cap" "int flags" "void *data" "size_t bytes" 48.Sh DESCRIPTION 49The 50.Fn syscap_get 51function returns the current flags for the requested capability. 52.Pp 53The 54.Fn syscap_set 55function add the specified flags to the restrictions applied to a 56specific capability for the current process. 57The flags are bitwise ORd into the capability. 58Capability restrictions cannot be removed once set. 59.Sh GENERAL 60Capability restrictions mostly apply to the root user. Capability 61restrictions are grouped in sets of 16. Group 0 restrictions 62also restrict all capabilities in group N. For example, the 63SYSCAP_RESTRICTEDROOT capability (group 0 capability 1) also 64restricts all capabilities in group 1. 65.Pp 66Capabillities are applied to the current process or its parent process. 67All threads in a process share the same capabilities. 68.Pp 69One can create a relatively (but not completely) secure root environment 70without jails by combining numerous capability restrictions with a chrooted 71environment into a filesystem topology constructed from null mounts and 72tmpfs mounts. The following capabilities are commonly employed when 73creating such environments: SYSCAP_RESTRICTEDROOT, SYSCAP_SENSITIVEROOT, 74SYSCAP_NONET_SENSITIVE, SYSCAP_NOVFS_SENSITIVE, SYSCAP_NOMOUNT, and 75possibly also SYSCAP_NOEXEC_SUID and SYSCAP_NOEXEC_SGID. 76.Pp 77.Sh GROUP 0 CAPABILITIES (also disable their related sub-groups) 78.Bl -tag -width Dv 79.It Dv SYSCAP_ANY 80Returns flags that are a wire-or of all other capabilities, indicating that 81some mucking around with capabilities was done. Generally not explicitly set. 82.It Dv SYSCAP_RESTRICTEDROOT 83Restricts all group 1 capabilities. These are capabililties which most 84root-run programs should never need to use. 85.Pp 86Most modifying root operations not available as separate capabilities 87are also restricted by this capability. 88.It Dv SYSCAP_SENSITIVEROOT 89Restrict all group 2 capabilities. These are capabilities that most 90root-run scripts probably don't need. 91.It Dv SYSCAP_NOEXEC 92Restricts ALL exec*() system calls, including the ones in group 3. 93However, it is generally not a good idea to prevent execs entirely except 94in the depths of a well controlled program. 95.It Dv SYSCAP_NOCRED 96Restrict all cred system calls, such as setuid() that are otherwise not 97generally restricted by RESTRICTEDROOT. These are capabilities that most 98root run scripts do not need to use unless they are messing around 99with pty's and terminal emulation. 100.It Dv SYSCAP_NOJAIL 101Restrict all jail related system calls. 102.It Dv SYSCAP_NONET 103Restrict all network related system calls (if you also do NONET_SENSITIVE in 104addition to this one), generally preventing the use of reserved ports or 105raw sockets. Note that numerous applications use reserved ports. 106.It Dv SYSCAP_NONET_SENSITIVE 107Restrict all sensitive network related system calls such as ifconfig, packet 108filter, and other related operations that most programs and scripts do not 109need to mess with. 110.It Dv SYSCAP_NOVFS 111Restrict all vfs related system calls (if you also do NOVFS_SENSITIVE in 112addition to this one), generally only allowing basic file open, 113close, read, and write, and disallowing things like chown, chmod, chroot, 114and so forth. 115.It Dv SYSCAP_NOVFS_SENSITIVE 116Restrict all sensitive vfs related system calls such as mknod and filesystem 117control ioctls. 118.It Dv SYSCAP_NOMOUNT 119Restrict all mount and umount operations. This can be combined with a 120chrooted environment to create secure filesystem topologies. Read-only 121null mounts are a very powerful tool for creating such environments 122cheaply. 123.El 124.Sh GROUP 1 CAPABILITIES (ALSO DISABLED BY SYSCAP_RESTRICTEDROOT) 125.Bl -tag -width Dv 126.It Dv SYSCAP_NODRIVER 127Restrict most driver-related ioctls. 128.It Dv SYSCAP_NOVM_MLOCK 129Restrict mlock() calls. 130.It Dv SYSCAP_NOVM_RESIDENT 131Restrict access to mechanisms which cache already-relocated dynamic 132binaries in memory. 133.It Dv SYSCAP_NOCPUCTL_WRMSR 134Restrict access to CPUCTL_WRMSR (cpu control registers). 135.It Dv SYSCAP_NOCPUCTL_UPDATE 136Restrict access to CPUCTL_UPDATE (cpu control registers). 137.It Dv SYSCAP_NOACCT 138Restrict access to the acct() system call. 139.It Dv SYSCAP_NOKENV_WR 140Restrict the ability to write to the kernel environment table. 141.It Dv SYSCAP_NOKLD 142Disallow kldload, kldunload, and device firmware loading. 143.It Dv SYSCAP_NOKERN_WR 144Disallow general modifications to kernel space (these are mostly 145covered by the over-arching RESTRICTEDROOT capability). 146.It Dv SYSCAP_NOREBOOT 147Disallow rebooting and also disallow signaling process 1. 148.El 149.Sh GROUP 2 CAPABILITIES (ALSO DISABLED BY SYSCAP_SENSITIVEROOT) 150.Bl -tag -width Dv 151.It Dv SYSCAP_NOPROC_TRESPASS 152Do not allow cross-uid process signaling beyond simple uid checks. 153uid 0 can still signal non-uid-0 processes as long as SYSCAP_RESTRICTEDROOT 154is active for those processes. 155.It Dv SYSCAP_NOPROC_SETLOGIN 156Disallow use of the setlogin() system call. 157.It Dv SYSCAP_NOPROC_SETRLIMIT 158Do not allow root to raise process resource limits. 159.It Dv SYSCAP_NOSYSCTL_WR 160Do not allow modifying global sysctl() calls. 161.It Dv SYSCAP_NOVARSYM_SYS 162Do not allow modifying system-level varsym operations. 163.It Dv SYSCAP_NOSETHOSTNAME 164Disallow use of the sethostname() system call. 165.It Dv SYSCAP_NOQUOTA_WR 166Disallow use of all modifying filesystem quota operations. 167.It Dv SYSCAP_NODEBUG_UNPRIV 168Do not allow the debugger to be entered via sysctl or root access 169via procfs. 170.It Dv SYSCAP_NOSETTIME 171Do not allow the system time to be set or adjusted. 172.It Dv SYSCAP_NOSCHED 173Do not allow the system scheduler to be changed, rtprio, or 174priority raising. 175.It Dv SYSCAP_NOSCHED_CPUSET 176Do not allow the cpuset to be restricted via scheduler calls. 177.El 178.Sh GROUP 3 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOEXEC) 179.Bl -tag -width Dv 180.It Dv SYSCAP_NOEXEC_SUID 181Do not allow suid execs. 182.It Dv SYSCAP_NOEXEC_SGID 183Do not allow sgid execs. 184.El 185.Sh GROUP 4 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOCRED) 186.Bl -tag -width Dv 187.It Dv SYSCAP_NOCRED_SETUID 188.It Dv SYSCAP_NOCRED_SETGID 189.It Dv SYSCAP_NOCRED_SETEUID 190.It Dv SYSCAP_NOCRED_SETEGID 191.It Dv SYSCAP_NOCRED_SETREUID 192.It Dv SYSCAP_NOCRED_SETREGID 193.It Dv SYSCAP_NOCRED_SETRESUID 194.It Dv SYSCAP_NOCRED_SETRESGID 195.It Dv SYSCAP_NOCRED_SETGROUPS 196Do not allow various cred related system calls. 197.El 198.Sh GROUP 5 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOJAIL) 199.Bl -tag -width Dv 200.It Dv SYSCAP_NOJAIL_CREATE 201Do not allow jail creates. 202.It Dv SYSCAP_NOJAIL_ATTACH 203Do not allow jail attachments. 204.El 205.Sh GROUP 6 CAPABILITIES (ALSO DISABLED BY SYSCAP_NONET) 206.Bl -tag -width Dv 207.It Dv SYSCAP_NONET_RESPORT 208Do not allow ports in the reserved ranges to be bound. 209.It Dv SYSCAP_NONET_RAW 210Do not allow use of raw sockets. 211.El 212.Sh GROUP 7 CAPABILITIES (ALSO DISABLED BY SYSCAP_NONET_SENSITIVE) 213.Bl -tag -width Dv 214 215.It Dv SYSCAP_NONET_IFCONFIG 216Do not allow modifications to NICs via ifconfig. 217.It Dv SYSCAP_NONET_ROUTE 218Do not allow modifications to the route table (not implemented yet). 219.It Dv SYSCAP_NONET_LAGG 220Do not allow modifications to LAGG interfaces. 221.It Dv SYSCAP_NONET_NETGRAPH 222Do not allow modifying netgraph operations. 223.It Dv SYSCAP_NONET_BT_RAW 224Do not allow raw bluetooth operations. 225.It Dv SYSCAP_NONET_WIFI 226Do not allow wifi related device ioctls. 227.El 228.Sh GROUP 8 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOVFS) 229.Bl -tag -width Dv 230.It Dv SYSCAP_NOVFS_SYSFLAGS 231Do not allow chflags on files not owned by the user even if modes 232or group allow such operations. 233.It Dv SYSCAP_NOVFS_CHOWN 234Do not allow chown operations on files. 235.It Dv SYSCAP_NOVFS_CHMOD 236Do not allow chmod operations on files. 237.It Dv SYSCAP_NOVFS_LINK 238Do not allow hard links. 239.It Dv SYSCAP_NOVFS_CHFLAGS_DEV 240Do not allow chflags on device nodes. 241.It Dv SYSCAP_NOVFS_SETATTR 242If set, prevents most file attribute changes. This should be used only 243by programs who know for damn sure that none of the library calls they 244make depend on chflags, chmod(), and other file related functions 245(obsolete). 246.It Dv SYSCAP_NOVFS_SETGID 247If set, clears SGID during certain file operations in UFS (obsolete). 248.It Dv SYSCAP_NOVFS_GENERATION 249File generation number will be reported as 0 in *stat() calls. 250.It Dv SYSCAP_NOVFS_RETAINSUGID 251If restricted, SUID and SGID bits are cleared when a file is written to. 252Otherwise normal unix operation is to not clear the bits. 253.El 254.Sh GROUP 9 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOVFS_SENSITIVE) 255.Bl -tag -width Dv 256.It Dv SYSCAP_NOVFS_MKNOD_BAD 257Do not allow mknod() to create bad entries. 258.It Dv SYSCAP_NOVFS_MKNOD_WHT 259Do not allow mknod() to create whitespace entries. 260.It Dv SYSCAP_NOVFS_MKNOD_DIR 261Do not allow mknod() to create directories. 262.It Dv SYSCAP_NOVFS_MKNOD_DEV 263Do not allow mknod() to create devices. 264.It Dv SYSCAP_NOVFS_IOCTL 265Disallow use of sensitive filesystem related ioctls(). 266.It Dv SYSCAP_NOVFS_CHROOT 267Disallow use of the chroot() system call. 268.It Dv SYSCAP_NOVFS_REVOKE 269Disallow use of the revoke() system call. 270.El 271.Sh GROUP 10 CAPABILITIES (ALSO DISABLED BY SYSCAP_NOMOUNT) 272.Bl -tag -width Dv 273.It Dv SYSCAP_NOMOUNT_NULLFS 274Disallow nullfs mounts. 275.It Dv SYSCAP_NOMOUNT_DEVFS 276Disallow devfs mounts. 277.It Dv SYSCAP_NOMOUNT_TMPFS 278Disallow tmpfs mounts. 279.It Dv SYSCAP_NOMOUNT_UMOUNT 280Disallow unmounts. 281.It Dv SYSCAP_NOMOUNT_FUSE 282Disallow fuse mounts and unmounts. 283.El 284.Sh CAPABILITY DIRECTOR FLAGS (or'd with cap, not the flags) 285.Bl -tag -width Dv 286.It Dv __SYSCAP_INPARENT 287Adjusts the capability in the parent process of the calling process. 288If not specified, the capability in the calling process is adjusted. 289The parent process must be in the same jail and have the same uid. 290.El 291.Sh FLAGS (flags argument) 292.Bl -tag -width Dv 293.It Dv __SYSCAP_SELF 294A bit mask indicating the restriction is applied to the calling process 295(or parent process if the capabliity is directed to __SYSCAP_INPARENT ), 296including process fork()s. 297.It Dv __SYSCAP_EXEC 298A bit mask indicating the restriction is applied to any exec performed 299by the process. This bit is shifted into the __SYSCAP_SELF bit upon a 300successful exec*(). The __SYSCAP_EXEC bit is retained so all deeper 301applications will wind up with both bits set. 302.It Dv __SYSCAP_ALL 303A multi-bit mask that covers both SELF and EXEC 304.El 305.Sh ERRORS 306These functions return the current or post-modified capability flags 307for the specified capability, or returns -1 with errno set as follows. 308.Bl -tag -width Er 309.It Bq Er EOPNOTSUPP 310The requested capability does not exist or is not supported. 311.It Bq Er EINVAL 312An invalid parameter was passed. This can be an illegal flag, 313improper pointer, unsupported structure size, or unsupported 314content that is not otherwise ignored by the system. 315.El 316.Sh SEE ALSO 317.Xr syscap_set 2 318.Sh HISTORY 319The 320.Fn syscap_get 321and 322.Fn syscap_set 323functions first appeared in 324.Dx 6.5 . 325