summaryrefslogtreecommitdiff
path: root/lib/libc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc')
-rw-r--r--lib/libc/sys/pledge.2712
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 .