123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300 | PLEDGE(2) System Calls Manual PLEDGE(2)
NNAAMMEE
pplleeddggee - restrict system operations
SSYYNNOOPPSSIISS
##iinncclluuddee <<uunniissttdd..hh>>
_i_n_t
pplleeddggee(_c_o_n_s_t _c_h_a_r _*_p_r_o_m_i_s_e_s, _c_o_n_s_t _c_h_a_r _*_e_x_e_c_p_r_o_m_i_s_e_s);
DDEESSCCRRIIPPTTIIOONN
The pplleeddggee() 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 notably separate, DNS
resolution). In general, these modes were selected by studying the
operation of many programs using libc and other such interfaces, and
setting _p_r_o_m_i_s_e_s or _e_x_e_c_p_r_o_m_i_s_e_s.
Use of pplleeddggee() in an application will require at least some study and
understanding of the interfaces called. Subsequent calls to pplleeddggee() can
reduce the abilities further, but abilities can never be regained.
A process which attempts a restricted operation is killed with an
uncatchable SIGABRT, delivering a core file if possible. A process
currently running with pledge has state `p' in ps(1) output; a process
that was terminated due to a pledge violation is accounted by lastcomm(1)
with the `P' flag.
A _p_r_o_m_i_s_e_s value of "" restricts the process to the _exit(2) system call.
This can be used for pure computation operating on memory shared with
another process.
Passing NULL to _p_r_o_m_i_s_e_s or _e_x_e_c_p_r_o_m_i_s_e_s specifies to not change the
current value.
Some system calls, when allowed, have restrictions applied to them:
access(2):
May check for existence of _/_e_t_c_/_l_o_c_a_l_t_i_m_e.
adjtime(2):
Read-only, for ntpd(8).
chmod(2), fchmod(2), fchmodat(2), chown(2), lchown(2), fchown(2),
fchownat(2), mkfifo(2), and mknod(2):
Setuid/setgid/sticky bits are ignored. The user or group cannot be
changed on a file.
ioctl(2):
Only the FIONREAD, FIONBIO, FIOCLEX, and FIONCLEX operations are
allowed by default. Various ioctl requests are allowed against
specific file descriptors based upon the requests aauuddiioo, bbppff,
ddiisskkllaabbeell, ddrrmm, iinneett, ppff, rroouuttee, wwrroouuttee, ttaappee, ttttyy, vviiddeeoo, and vvmmmm.
mmap(2) and mprotect(2):
PROT_EXEC isn't allowed.
open(2):
May open _/_e_t_c_/_l_o_c_a_l_t_i_m_e and any files below _/_u_s_r_/_s_h_a_r_e_/_z_o_n_e_i_n_f_o.
profil(2):
Can only disable profiling.
pplleeddggee():
Can only reduce permissions for _p_r_o_m_i_s_e_s and _e_x_e_c_p_r_o_m_i_s_e_s.
sysctl(2):
A small set of read-only operations are allowed, sufficient to
support: getdomainname(3), gethostname(3), getifaddrs(3), uname(3),
and system sensor readings.
The _p_r_o_m_i_s_e_s argument is specified as a string, with space separated
keywords:
ssttddiioo The following system calls are permitted. sendto(2) is
only permitted if its destination socket address is
NULL. As a result, all the expected functionalities of
libc stdio work.
clock_getres(2), clock_gettime(2), close(2),
closefrom(2), dup(2), dup2(2), dup3(2), fchdir(2),
fcntl(2), fstat(2), fsync(2), ftruncate(2),
getdtablecount(2), getegid(2), getentropy(2),
geteuid(2), getgid(2), getgroups(2), getitimer(2),
getlogin(2), getpgid(2), getpgrp(2), getpid(2),
getppid(2), getresgid(2), getresuid(2), getrlimit(2),
getrtable(2), getsid(2), getthrid(2), gettimeofday(2),
getuid(2), issetugid(2), kevent(2), kqueue(2),
kqueue1(2), lseek(2), madvise(2), minherit(2), mmap(2),
mprotect(2), mquery(2), munmap(2), nanosleep(2),
pipe(2), pipe2(2), poll(2), pread(2), preadv(2),
profil(2), pwrite(2), pwritev(2), read(2), readv(2),
recvfrom(2), recvmsg(2), select(2), sendmsg(2),
sendsyslog(2), sendto(2), setitimer(2), shutdown(2),
sigaction(2), sigprocmask(2), sigreturn(2),
socketpair(2), umask(2), wait4(2), waitid(2), write(2),
writev(2)
rrppaatthh A number of system calls are allowed if they only cause
read-only effects on the filesystem, or expose filenames
to programs:
chdir(2), getcwd(3), getdents(2), openat(2), fstatat(2),
faccessat(2), readlinkat(2), lstat(2), chmod(2),
fchmod(2), fchmodat(2), chflags(2), chflagsat(2),
chown(2), fchown(2), fchownat(2), fstat(2), getfsstat(2)
wwppaatthh A number of system calls are allowed and may cause
write-effects on the filesystem:
getcwd(3), openat(2), fstatat(2), faccessat(2),
readlinkat(2), lstat(2), chmod(2), fchmod(2),
fchmodat(2), chflags(2), chflagsat(2), chown(2),
fchown(2), fchownat(2), fstat(2)
ccppaatthh A number of system calls and sub-modes are allowed,
which may create new files or directories in the
filesystem:
rename(2), renameat(2), link(2), linkat(2), symlink(2),
symlinkat(2), unlink(2), unlinkat(2), mkdir(2),
mkdirat(2), rmdir(2)
ddppaatthh A number of system calls are allowed to create special
files:
mkfifo(2), mknod(2)
ttmmppppaatthh A number of system calls are allowed to do operations in
the _/_t_m_p directory, including create, read, or write:
lstat(2), chmod(2), chflags(2), chown(2), unlink(2),
fstat(2)
iinneett The following system calls are allowed to operate in the
AF_INET and AF_INET6 domains (though setsockopt(2) has
been substantially reduced in functionality):
socket(2), listen(2), bind(2), connect(2), accept4(2),
accept(2), getpeername(2), getsockname(2),
setsockopt(2), getsockopt(2)
mmccaasstt In combination with iinneett give back functionality to
setsockopt(2) for operating on multicast sockets.
ffaattttrr The following system calls are allowed to make explicit
changes to fields in _s_t_r_u_c_t _s_t_a_t relating to a file:
utimes(2), futimes(2), utimensat(2), futimens(2),
chmod(2), fchmod(2), fchmodat(2), chflags(2),
chflagsat(2), chown(2), fchownat(2), lchown(2),
fchown(2), utimes(2)
cchhoowwnn The chown(2) family is allowed to change the user or
group on a file.
fflloocckk File locking via fcntl(2), flock(2), lockf(3), and
open(2) is allowed. No distinction is made between
shared and exclusive locks. This promise is required
for unlock as well as lock.
uunniixx The following system calls are allowed to operate in the
AF_UNIX domain:
socket(2), listen(2), bind(2), connect(2), accept4(2),
accept(2), getpeername(2), getsockname(2),
setsockopt(2), getsockopt(2)
ddnnss Subsequent to a successful open(2) of _/_e_t_c_/_r_e_s_o_l_v_._c_o_n_f,
a few system calls become able to allow DNS network
transactions:
sendto(2), recvfrom(2), socket(2), connect(2)
ggeettppww This allows read-only opening of files in _/_e_t_c for the
getpwnam(3), getgrnam(3), getgrouplist(3), and
initgroups(3) family of functions, including lookups via
the yp(8) protocol for YP and LDAP databases.
sseennddffdd Allows sending of file descriptors using sendmsg(2).
File descriptors referring to directories may not be
passed.
rreeccvvffdd Allows receiving of file descriptors using recvmsg(2).
File descriptors referring to directories may not be
passed.
ttaappee Allow MTIOCGET and MTIOCTOP operations against tape
drives.
ttttyy In addition to allowing read-write operations on
_/_d_e_v_/_t_t_y, this opens up a variety of ioctl(2) requests
used by tty devices. If ttttyy is accompanied with rrppaatthh,
revoke(2) is permitted. Otherwise only the following
ioctl(2) requests are permitted:
TIOCSPGRP, TIOCGETA, TIOCGPGRP, TIOCGWINSZ, TIOCSWINSZ,
TIOCSBRK, TIOCCDTR, TIOCSETA, TIOCSETAW, TIOCSETAF,
TIOCUCNTL
pprroocc Allows the following process relationship operations:
fork(2), vfork(2), kill(2), getpriority(2),
setpriority(2), setrlimit(2), setpgid(2), setsid(2)
eexxeecc Allows a process to call execve(2). Coupled with the
pprroocc promise, this allows a process to fork and execute
another program. If _e_x_e_c_p_r_o_m_i_s_e_s has been previously
set the new program begins with those promises, unless
setuid/setgid bits are set in which case execution is
blocked with EACCES. Otherwise the new program starts
running without pledge active, and hopefully makes a new
pledge soon.
pprroott__eexxeecc Allows the use of PROT_EXEC with mmap(2) and
mprotect(2).
sseettttiimmee Allows the setting of system time, via the
settimeofday(2), adjtime(2), and adjfreq(2) system
calls.
ppss Allows enough sysctl(2) interfaces to allow inspection
of processes operating on the system using programs like
ps(1).
vvmmiinnffoo Allows enough sysctl(2) interfaces to allow inspection
of the system's virtual memory by programs like top(1)
and vmstat(8).
iidd Allows the following system calls which can change the
rights of a process:
setuid(2), seteuid(2), setreuid(2), setresuid(2),
setgid(2), setegid(2), setregid(2), setresgid(2),
setgroups(2), setlogin(2), setrlimit(2), getpriority(2),
setpriority(2), setrtable(2)
ppff Allows a subset of ioctl(2) operations on the pf(4)
device:
DIOCADDRULE, DIOCGETSTATUS, DIOCNATLOOK, DIOCRADDTABLES,
DIOCRCLRADDRS, DIOCRCLRTABLES, DIOCRCLRTSTATS,
DIOCRGETTSTATS, DIOCRSETADDRS, DIOCXBEGIN, DIOCXCOMMIT
rroouuttee Allow inspection of the routing table.
wwrroouuttee Allow changes to the routing table.
aauuddiioo Allows a subset of ioctl(2) operations on audio(4)
devices (see sio_open(3) for more information):
AUDIO_GETPOS, AUDIO_GETPAR, AUDIO_SETPAR, AUDIO_START,
AUDIO_STOP, AUDIO_MIXER_DEVINFO, AUDIO_MIXER_READ,
AUDIO_MIXER_WRITE
vviiddeeoo Allows a subset of ioctl(2) operations on video(4)
devices:
VIDIOC_DQBUF, VIDIOC_ENUM_FMT,
VIDIOC_ENUM_FRAMEINTERVALS, VIDIOC_ENUM_FRAMESIZES,
VIDIOC_G_CTRL, VIDIOC_G_PARM, VIDIOC_QBUF,
VIDIOC_QUERYBUF, VIDIOC_QUERYCAP, VIDIOC_QUERYCTRL,
VIDIOC_S_CTRL, VIDIOC_S_FMT, VIDIOC_S_PARM,
VIDIOC_STREAMOFF, VIDIOC_STREAMON, VIDIOC_TRY_FMT,
VIDIOC_REQBUFS
bbppff Allow BIOCGSTATS operation for statistics collection
from a bpf(4) device.
uunnvveeiill Allow unveil(2) to be called.
eerrrroorr Rather than killing the process upon violation, indicate
error with ENOSYS.
Also when pplleeddggee() is called with higher _p_r_o_m_i_s_e_s or
_e_x_e_c_p_r_o_m_i_s_e_s, those changes will be ignored and return
success. This is useful when a parent enforces
_e_x_e_c_p_r_o_m_i_s_e_s but an execve'd child has a different idea.
RREETTUURRNN VVAALLUUEESS
Upon successful completion, the value 0 is returned; otherwise the
value -1 is returned and the global variable _e_r_r_n_o is set to indicate the
error.
EERRRROORRSS
pplleeddggee() will fail if:
[EFAULT] _p_r_o_m_i_s_e_s or _e_x_e_c_p_r_o_m_i_s_e_s points outside the process's
allocated address space.
[EINVAL] _p_r_o_m_i_s_e_s is malformed or contains invalid keywords.
[EPERM] This process is attempting to increase permissions.
HHIISSTTOORRYY
The pplleeddggee() system call first appeared in OpenBSD 5.9.
OpenBSD 7.6 September 17, 2024 OpenBSD 7.6
|