diff options
author | Jason McIntyre <jmc@cvs.openbsd.org> | 2018-03-04 16:47:44 +0000 |
---|---|---|
committer | Jason McIntyre <jmc@cvs.openbsd.org> | 2018-03-04 16:47:44 +0000 |
commit | 04ca4a192379dc9138601cf77dcfebeddf28c593 (patch) | |
tree | cdcf98865a8bf8ec5f8efdfc90910e810a82ec92 /lib/libc | |
parent | 06d1e743b7b8f9115ac239717694c4c65b056f3a (diff) |
various tweaks, in part to try and clean up the amount of vertical
whitespace in this page;
ok deraadt
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/sys/pledge.2 | 712 |
1 files changed, 351 insertions, 361 deletions
diff --git a/lib/libc/sys/pledge.2 b/lib/libc/sys/pledge.2 index 64a12bc1f15..a73f10d83b4 100644 --- a/lib/libc/sys/pledge.2 +++ b/lib/libc/sys/pledge.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pledge.2,v 1.50 2018/01/12 04:36:44 deraadt Exp $ +.\" $OpenBSD: pledge.2,v 1.51 2018/03/04 16:47:43 jmc Exp $ .\" .\" Copyright (c) 2015 Nicholas Marriott <nicm@openbsd.org> .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 12 2018 $ +.Dd $Mdocdate: March 4 2018 $ .Dt PLEDGE 2 .Os .Sh NAME @@ -25,10 +25,12 @@ .Ft int .Fn pledge "const char *promises" "const char *execpromises" .Sh DESCRIPTION -The current process is forced into a restricted-service operating mode. +The +.Nm pledge +system call forces the current process into a restricted-service operating mode. A few subsets are available, roughly described as computation, memory management, read-write operations on file descriptors, opening of files, -networking. +and networking. In general, these modes were selected by studying the operation of many programs using libc and other such interfaces, and setting .Ar promises @@ -36,11 +38,11 @@ or .Ar execpromises . .Pp Use of -.Fn pledge +.Nm pledge in an application will require at least some study and understanding of the interfaces called. Subsequent calls to -.Fn pledge +.Nm pledge can reduce the abilities further, but abilities can never be regained. .Pp A process which attempts a restricted operation is killed with an uncatchable @@ -74,17 +76,28 @@ or specifies to not change the current value. .Pp Some system calls, when allowed, have restrictions applied to them: -.Pp -.Bl -tag -width "readlink(2)" -offset indent -compact -.It Xr access 2 +.Bl -ohang -offset indent +.It Xr access 2 : May check for existence of .Pa /etc/localtime . -.Pp -.It Xr adjtime 2 +.It Xr adjtime 2 : Read-only, for .Xr ntpd 8 . -.Pp -.It Xr ioctl 2 +.It Xo +.Xr chmod 2 , +.Xr fchmod 2 , +.Xr fchmodat 2 , +.Xr chown 2 , +.Xr lchown 2 , +.Xr fchown 2 , +.Xr fchownat 2 , +.Xr mkfifo 2 , +and +.Xr mknod 2 : +.Xc +Setuid/setgid/sticky bits are ignored. +The user or group cannot be changed on a file. +.It Xr ioctl 2 : Only the .Dv FIONREAD , .Dv FIONBIO , @@ -105,58 +118,299 @@ based upon the requests .Va tty , and .Va vmm . -.Pp -.It Xr chmod 2 -.It Xr fchmod 2 -.It Xr fchmodat 2 -.It Xr chown 2 -.It Xr lchown 2 -.It Xr fchown 2 -.It Xr fchownat 2 -.It Xr mkfifo 2 -.It Xr mknod 2 -Setuid/setgid/sticky bits are ignored. -The user or group cannot be changed on a file. -.Pp -.It Xr mmap 2 -.It Xr mprotect 2 +.It Xo +.Xr mmap 2 +and +.Xr mprotect 2 : +.Xc .Dv PROT_EXEC isn't allowed. -.Pp -.It Xr open 2 +.It Xr open 2 : May open .Pa /etc/localtime and any files below .Pa /usr/share/zoneinfo . -.Pp -.It Xr readlink 2 +.It Nm pledge : +Can only reduce permissions for +.Ar promises +and +.Ar execpromises . +.It Xr readlink 2 : May operate on .Pa /etc/malloc.conf . -.Pp -.It Xr sysctl 2 +.It Xr sysctl 2 : A small set of read-only operations are allowed, sufficient to support: .Xr getdomainname 3 , .Xr gethostname 3 , .Xr getifaddrs 3 , .Xr uname 3 , -system sensor readings. +and system sensor readings. +.El .Pp -.It Fn pledge -Can only reduce permissions for +The .Ar promises -and -.Ar execpromises . -.El +argument is specified as a string, with space separated keywords: +.Bl -tag -width "prot_exec" -offset indent +.It Va audio +Allows a subset of +.Xr ioctl 2 +operations on +.Xr audio 4 +devices +(see +.Xr sio_open 3 +for more information): .Pp +.Dv AUDIO_GETPOS , +.Dv AUDIO_GETPAR , +.Dv AUDIO_SETPAR , +.Dv AUDIO_START , +.Dv AUDIO_STOP +.It Va bpf +Allow +.Dv BIOCGSTATS +operation for statistics collection from a +.Xr bpf 4 +device. +.It Va chown The +.Xr chown 2 +family is allowed to change the user or group on a file. +.It Va cpath +A number of system calls and sub-modes are allowed, which may +create new files or directories in the filesystem: +.Pp +.Xr rename 2 , +.Xr renameat 2 , +.Xr link 2 , +.Xr linkat 2 , +.Xr symlink 2 , +.Xr symlinkat 2 , +.Xr unlink 2 , +.Xr unlinkat 2 , +.Xr mkdir 2 , +.Xr mkdirat 2 , +.Xr rmdir 2 +.It Va dns +Subsequent to a successful +.Xr open 2 +of +.Pa /etc/resolv.conf , +a few system calls become able to allow DNS network transactions: +.Pp +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr socket 2 , +.Xr connect 2 +.It Va dpath +A number of system calls are allowed to create special files: +.Pp +.Xr mkfifo 2 , +.Xr mknod 2 +.It Va error +Rather than killing the process upon violation, indicate error with +.Er ENOSYS . +.Pp +Also when +.Nm pledge +is called with higher .Ar promises -is specified as a string, with space separated keywords: -.Bl -tag -width "tmppath" -offset indent +or +.Ar execpromises , +those changes will be ignored and return success. +This is useful when a parent enforces +.Ar execpromises +but an execve'd child has a different idea. +.It Va exec +Allows a process to call +.Xr execve 2 . +Coupled with the +.Va proc +promise, this allows a process to fork and execute another program. +If +.Ar execpromises +has been previously set the new program begins with those promises, +unless setuid/setgid bits are set in which case execution is blocked with +.Er EACCESS . +Otherwise the new program starts running without pledge active, +and hopefully makes a new pledge soon. +.It Va fattr +The following system calls are allowed to make explicit changes +to fields in +.Va struct stat +relating to a file: +.Pp +.Xr utimes 2 , +.Xr futimes 2 , +.Xr utimensat 2 , +.Xr futimens 2 , +.Xr chmod 2 , +.Xr fchmod 2 , +.Xr fchmodat 2 , +.Xr chflags 2 , +.Xr chflagsat 2 , +.Xr chown 2 , +.Xr fchownat 2 , +.Xr lchown 2 , +.Xr fchown 2 , +.Xr utimes 2 +.It Va flock +File locking via +.Xr fcntl 2 , +.Xr flock 2 , +.Xr lockf 3 , +and +.Xr open 2 +is allowed. +No distinction is made between shared and exclusive locks. +This promise is required for unlock as well as lock. +.It Va getpw +This allows read-only opening of files in +.Pa /etc +for the +.Xr getpwnam 3 , +.Xr getgrnam 3 , +.Xr getgrouplist 3 , +and +.Xr initgroups 3 +family of functions. +They may also need to operate in a +.Xr yp 8 +environment, so a successful +.Xr open 2 +of +.Pa /var/run/ypbind.lock +enables +.Va inet +operations. +.It Va id +Allows the following system calls which can change the rights of a +process: +.Pp +.Xr setuid 2 , +.Xr seteuid 2 , +.Xr setreuid 2 , +.Xr setresuid 2 , +.Xr setgid 2 , +.Xr setegid 2 , +.Xr setregid 2 , +.Xr setresgid 2 , +.Xr setgroups 2 , +.Xr setlogin 2 , +.Xr setrlimit 2 , +.Xr getpriority 2 , +.Xr setpriority 2 +.It Va inet +The following system calls are allowed to operate in the +.Dv AF_INET +and +.Dv AF_INET6 +domains +(though +.Xr setsockopt 2 +has been substantially reduced in functionality): +.Pp +.Xr socket 2 , +.Xr listen 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr accept4 2 , +.Xr accept 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr setsockopt 2 , +.Xr getsockopt 2 +.It Va mcast +In combination with +.Va inet +give back functionality to +.Xr setsockopt 2 +for operating on multicast sockets. +.It Va pf +Allows a subset of +.Xr ioctl 2 +operations on the +.Xr pf 4 +device: +.Pp +.Dv DIOCADDRULE , +.Dv DIOCGETSTATUS , +.Dv DIOCNATLOOK , +.Dv DIOCRADDTABLES , +.Dv DIOCRCLRADDRS , +.Dv DIOCRCLRTABLES , +.Dv DIOCRCLRTSTATS , +.Dv DIOCRGETTSTATS , +.Dv DIOCRSETADDRS , +.Dv DIOCXBEGIN , +.Dv DIOCXCOMMIT +.It Va proc +Allows the following process relationship operations: +.Pp +.Xr fork 2 , +.Xr vfork 2 , +.Xr kill 2 , +.Xr getpriority 2 , +.Xr setpriority 2 , +.Xr setrlimit 2 , +.Xr setpgid 2 , +.Xr setsid 2 +.It Va prot_exec +Allows the use of +.Dv PROT_EXEC +with +.Xr mmap 2 +and +.Xr mprotect 2 . +.It Va ps +Allows enough +.Xr sysctl 2 +interfaces to allow inspection of processes operating on the system using +programs like +.Xr ps 1 . +.It Va recvfd +Allows receiving of file descriptors using +.Xr recvmsg 2 . +File descriptors referring to directories may not be passed. +.It Va rpath +A number of system calls are allowed if they only cause +read-only effects on the filesystem: +.Pp +.Xr chdir 2 , +.Xr getcwd 3 , +.Xr openat 2 , +.Xr fstatat 2 , +.Xr faccessat 2 , +.Xr readlinkat 2 , +.Xr lstat 2 , +.Xr chmod 2 , +.Xr fchmod 2 , +.Xr fchmodat 2 , +.Xr chflags 2 , +.Xr chflagsat 2 , +.Xr chown 2 , +.Xr fchown 2 , +.Xr fchownat 2 , +.Xr fstat 2 , +.Xr getfsstat 2 +.It Va sendfd +Allows sending of file descriptors using +.Xr sendmsg 2 . +File descriptors referring to directories may not be passed. +.It Va settime +Allows the setting of system time, via the +.Xr settimeofday 2 , +.Xr adjtime 2 , +and +.Xr adjfreq 2 +system calls. .It Va stdio -The following system calls are permitted to allow most basic functions -in libc, including memory allocation, most types of IO operations on -previously allocated file descriptors: +The following system calls are permitted. +.Xr sendto 2 +is only permitted if its destination socket address is +.Dv NULL . +As a result, all the expected functionalities of libc stdio work. .Pp .Xr clock_getres 2 , .Xr clock_gettime 2 , @@ -226,73 +480,13 @@ previously allocated file descriptors: .Xr umask 2 , .Xr wait4 2 , .Xr write 2 , -.Xr writev 2 . -.Pp -Note that -.Xr sendto 2 -is only permitted if its destination socket address is -.Dv NULL . -As a result, all the expected functionalities of libc stdio work. -.It Va rpath -A number of system calls are allowed if they only cause -read-only effects on the filesystem: -.Pp -.Xr chdir 2 , -.Xr getcwd 3 , -.Xr openat 2 , -.Xr fstatat 2 , -.Xr faccessat 2 , -.Xr readlinkat 2 , -.Xr lstat 2 , -.Xr chmod 2 , -.Xr fchmod 2 , -.Xr fchmodat 2 , -.Xr chflags 2 , -.Xr chflagsat 2 , -.Xr chown 2 , -.Xr fchown 2 , -.Xr fchownat 2 , -.Xr fstat 2 , -.Xr getfsstat 2 . -.It Va wpath -A number of system calls are allowed and may cause -write-effects on the filesystem: -.Pp -.Xr getcwd 3 , -.Xr openat 2 , -.Xr fstatat 2 , -.Xr faccessat 2 , -.Xr readlinkat 2 , -.Xr lstat 2 , -.Xr chmod 2 , -.Xr fchmod 2 , -.Xr fchmodat 2 , -.Xr chflags 2 , -.Xr chflagsat 2 , -.Xr chown 2 , -.Xr fchown 2 , -.Xr fchownat 2 , -.Xr fstat 2 . -.It Va cpath -A number of system calls and sub-modes are allowed, which may -create new files or directories in the filesystem: -.Pp -.Xr rename 2 , -.Xr renameat 2 , -.Xr link 2 , -.Xr linkat 2 , -.Xr symlink 2 , -.Xr symlinkat 2 , -.Xr unlink 2 , -.Xr unlinkat 2 , -.Xr mkdir 2 , -.Xr mkdirat 2 , -.Xr rmdir 2 . -.It Va dpath -A number of system calls are allowed to create special files: -.Pp -.Xr mkfifo 2 , -.Xr mknod 2 . +.Xr writev 2 +.It Va tape +Allow +.Dv MTIOCGET +and +.Dv MTIOCTOP +operations against tape drives. .It Va tmppath A number of system calls are allowed to do operations in the .Pa /tmp @@ -303,135 +497,23 @@ directory, including create, read, or write: .Xr chflags 2 , .Xr chown 2 , .Xr unlink 2 , -.Xr fstat 2 . -.It Va inet -The following system calls are allowed to operate in the -.Dv AF_INET -and -.Dv AF_INET6 -domains: -.Pp -.Xr socket 2 , -.Xr listen 2 , -.Xr bind 2 , -.Xr connect 2 , -.Xr accept4 2 , -.Xr accept 2 , -.Xr getpeername 2 , -.Xr getsockname 2 , -.Xr setsockopt 2 , -.Xr getsockopt 2 . -.Pp -.Xr setsockopt 2 -has been reduced in functionality substantially. -.It Va mcast -In combination with -.Va inet -give back functionality to -.Xr setsockopt 2 -for operating on multicast sockets. -.It Va fattr -The following system calls are allowed to make explicit changes -to fields in -.Va struct stat -relating to a file: -.Pp -.Xr utimes 2 , -.Xr futimes 2 , -.Xr utimensat 2 , -.Xr futimens 2 , -.Xr chmod 2 , -.Xr fchmod 2 , -.Xr fchmodat 2 , -.Xr chflags 2 , -.Xr chflagsat 2 , -.Xr chown 2 , -.Xr fchownat 2 , -.Xr lchown 2 , -.Xr fchown 2 , -.Xr utimes 2 . -.It Va chown -The -.Xr chown 2 -family is allowed to change the user or group on a file. -.It Va flock -File locking via -.Xr fcntl 2 , -.Xr flock 2 , -.Xr lockf 3 , -and -.Xr open 2 -is allowed. -No distinction is made between shared and exclusive locks. -This promise is required for unlock as well as lock. -.It Va unix -The following system calls are allowed to operate in the -.Dv AF_UNIX -domain: -.Pp -.Xr socket 2 , -.Xr listen 2 , -.Xr bind 2 , -.Xr connect 2 , -.Xr accept4 2 , -.Xr accept 2 , -.Xr getpeername 2 , -.Xr getsockname 2 , -.Xr setsockopt 2 , -.Xr getsockopt 2 . -.It Va dns -Subsequent to a successful -.Xr open 2 -of -.Pa /etc/resolv.conf , -a few system calls become able to allow DNS network transactions: -.Pp -.Xr sendto 2 , -.Xr recvfrom 2 , -.Xr socket 2 , -.Xr connect 2 . -.It Va getpw -This allows read-only opening of files in -.Pa /etc -for the -.Xr getpwnam 3 , -.Xr getgrnam 3 , -.Xr getgrouplist 3 , -and -.Xr initgroups 3 -family of functions. -They may also need to operate in a -.Xr yp 8 -environment, so a successful -.Xr open 2 -of -.Pa /var/run/ypbind.lock -enables -.Va inet -operations. -.It Va sendfd -Allows sending of file descriptors using -.Xr sendmsg 2 . -File descriptors referring to directories may not be passed. -.It Va recvfd -Allows receiving of file descriptors using -.Xr recvmsg 2 . -File descriptors referring to directories may not be passed. -.It Va tape -Allow -.Dv MTIOCGET -and -.Dv MTIOCTOP -operations against tape drives. +.Xr fstat 2 .It Va tty In addition to allowing read-write operations on .Pa /dev/tty , this opens up a variety of .Xr ioctl 2 requests used by tty devices. -The following +If +.Va tty +is accompanied with +.Va rpath , +.Xr revoke 2 +is permitted. +Otherwise only the following .Xr ioctl 2 requests are permitted: +.Pp .Dv TIOCSPGRP , .Dv TIOCGETA , .Dv TIOCGPGRP , @@ -441,62 +523,23 @@ requests are permitted: .Dv TIOCCDTR , .Dv TIOCSETA , .Dv TIOCSETAW , -.Dv TIOCSETAF -and -.Dv TIOCUCNTL . -.Pp -If -.Va tty -is accompanied with -.Va rpath , -.Xr revoke 2 -is permitted. -.It Va proc -Allows the following process relationship operations: +.Dv TIOCSETAF , +.Dv TIOCUCNTL +.It Va unix +The following system calls are allowed to operate in the +.Dv AF_UNIX +domain: .Pp -.Xr fork 2 , -.Xr vfork 2 , -.Xr kill 2 , -.Xr getpriority 2 , -.Xr setpriority 2 , -.Xr setrlimit 2 , -.Xr setpgid 2 , -.Xr setsid 2 . -.It Va exec -Allows a process to call -.Xr execve 2 . -Coupled with the -.Va proc -promise, this allows a process to fork and execute another program. -If -.Ar execpromises -has been previously set the new program begins with those promises, -unless setuid/setgid bits are set in which case execution is blocked with -.Er EACCESS . -Otherwise the new program starts running without pledge active, -and hopefully makes a new -.Fn pledge -soon. -.It Va prot_exec -Allows the use of -.Dv PROT_EXEC -with -.Xr mmap 2 -and -.Xr mprotect 2 . -.It Va settime -Allows the setting of system time, via the -.Xr settimeofday 2 , -.Xr adjtime 2 , -and -.Xr adjfreq 2 -system calls. -.It Va ps -Allows enough -.Xr sysctl 2 -interfaces to allow inspection of processes operating on the system using -programs like -.Xr ps 1 . +.Xr socket 2 , +.Xr listen 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr accept4 2 , +.Xr accept 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr setsockopt 2 , +.Xr getsockopt 2 .It Va vminfo Allows enough .Xr sysctl 2 @@ -505,83 +548,30 @@ programs like .Xr top 1 and .Xr vmstat 8 . -.It Va id -Allows the following system calls which can change the rights of a -process: -.Pp -.Xr setuid 2 , -.Xr seteuid 2 , -.Xr setreuid 2 , -.Xr setresuid 2 , -.Xr setgid 2 , -.Xr setegid 2 , -.Xr setregid 2 , -.Xr setresgid 2 , -.Xr setgroups 2 , -.Xr setlogin 2 , -.Xr setrlimit 2 , -.Xr getpriority 2 , -.Xr setpriority 2 . -.It Va pf -Allows a subset of -.Xr ioctl 2 -operations on the -.Xr pf 4 -device: -.Pp -.Dv DIOCADDRULE , -.Dv DIOCGETSTATUS , -.Dv DIOCNATLOOK , -.Dv DIOCRADDTABLES , -.Dv DIOCRCLRADDRS , -.Dv DIOCRCLRTABLES , -.Dv DIOCRCLRTSTATS , -.Dv DIOCRGETTSTATS , -.Dv DIOCRSETADDRS , -.Dv DIOCXBEGIN , -.Dv DIOCXCOMMIT . -.It Va audio -Allows a subset of -.Xr ioctl 2 -operations on -.Xr audio 4 -devices: -.Pp -.Dv AUDIO_GETPOS , -.Dv AUDIO_GETPAR , -.Dv AUDIO_SETPAR , -.Dv AUDIO_START , -.Dv AUDIO_STOP . -.Pp -See -.Xr sio_open 3 -for more information on using the sndio API in combination with -.Fn pledge . -.It Va bpf -Allow -.Dv BIOCGSTATS -operation for statistics collection from a -.Xr bpf 4 -device. -.It Va error -Rather than killing the process upon violation, indicate error with -.Er ENOSYS . +.It Va wpath +A number of system calls are allowed and may cause +write-effects on the filesystem: .Pp -Also when -.Fn pledge -is called with higher -.Ar promises -or -.Ar execpromises , -those changes will be ignored and return success. -This is useful when a parent enforces -.Ar execpromises -but an execve'd child has a different idea. +.Xr getcwd 3 , +.Xr openat 2 , +.Xr fstatat 2 , +.Xr faccessat 2 , +.Xr readlinkat 2 , +.Xr lstat 2 , +.Xr chmod 2 , +.Xr fchmod 2 , +.Xr fchmodat 2 , +.Xr chflags 2 , +.Xr chflagsat 2 , +.Xr chown 2 , +.Xr fchown 2 , +.Xr fchownat 2 , +.Xr fstat 2 .El .Sh RETURN VALUES .Rv -std .Sh ERRORS -.Fn pledge +.Nm pledge will fail if: .Bl -tag -width Er .It Bq Er EFAULT @@ -597,6 +587,6 @@ This process is attempting to increase permissions. .El .Sh HISTORY The -.Fn pledge +.Nm pledge system call first appeared in .Ox 5.9 . |