pledge(2) - OpenBSD manual pages (original) (raw)
NAME
pledge —restrict system operations
SYNOPSIS
#include <unistd.h>
intpledge(const char *promises, const char *execpromises);
DESCRIPTION
Thepledge() system call separates the POSIX feature set into a group of approximately 3 dozen subsystems. By calling pledge() the program can declare which subsystems it will need in the future in a space-separated string called promises. Subsystems not listed become unavailable, and most attempts to use operations in that subsystem result in the process being killed with an uncatchableSIGABRT, delivering a core file if possible.
Subsequent calls topledge() can reduce the subsystems which still work, but previously revoked subsystems cannot be re-activated.
Passing NULL topromises or execpromises specifies to not change the current value.
A few changes to POSIX behaviour come into effect on the first call topledge(), regardless of the promise arguments:
Time cannot be changed. Only the olddelta argument works.
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. User or group cannot be changed. The fattr promise relaxes this behaviour slightly.
Only the FIONREAD,FIONBIO, FIOCLEX, andFIONCLEX operations are allowed by default. All other ioctl operations are blocked, except for ones which are enabled by specific promises: audio,bpf, disklabel,drm, inet,pf, route,wroute, tape,tty, video, andvmm.
mmap(2) and mprotect(2):
PROT_EXEC is not allowed, unless the prot_exec promise is requested.
A few system files can be opened directly by libc internal code using this hidden symbol system call when specificpromises are requested, but applications cannot open those files themselves. This works even when rpath or wpath are absent andunveil(2) cannot block opening the files. These are the promises which can read special files: promises.
/etc/localtime (file or zoneinfo symbolic link)
/usr/share/zoneinfo/
/dev/null (for read and/or write)
/dev/tty (for read and/or write)
/etc/spwd.db (refused with EPERM)
/etc/pwd.db /etc/group /etc/netid
/etc/resolv.conf /etc/hosts /etc/services /etc/protocols
pledge():
Can only reduce permissions for promises andexecpromises.
A small set of read-only operations are allowed, sufficient to support:getdomainname(3),gethostname(3),getifaddrs(3), uname(3), and system sensor readings. Somepromises expose more read-only operations.
The promises argument is specified as a string, with space separated keywords. Using "" restricts the process to the _exit(2) system call (this can be used for pure computation operating on memory shared with another process).
This promise provides access to basic memory management, actions upon already open file descriptors, inspection of various process attributes, timer resources, and other subsystems generally considered safe because they only occur inside the process.. Many of these interfaces are then used inside higher-level libc functionality, which is why the name stdio was chosen. The following system calls are permitted:
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)
sendto(2) is only permitted if the destination socket address isNULL.
A number of system calls are allowed which allow path traversal, readingstruct stat, and opening files for read.
Similar to rpath, but files can be opened for write.
Similar to wpath, but files can also be created or removed.
Similar to cpath, but special files can be created using:
No longer available. This pledge was designed to satisfy themkstemp(3) family of functions. The limited filesystem access it provided is now disabled, so the promise has been removed and will returnEINVAL. It should be replaced by either allowing use of the whole filesystem, meaning "rpath wpath cpath", or use of unveil(2) with path "/tmp" andpermissions "rwc".
The following system calls are allowed to operate in theAF_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)
In combination with inet give back functionality to setsockopt(2) for operating on multicast sockets.
The following system calls are allowed to make explicit changes to fields in struct stat 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)
The chown(2) family is allowed to change the user or group on a file.
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.
The following system calls are allowed to operate in theAF_UNIX domain:
socket(2), listen(2), bind(2),connect(2), accept4(2),accept(2),getpeername(2),getsockname(2),setsockopt(2),getsockopt(2)
The bind(2) call can create AF_UNIX sockets at any path even withoutwpath, andconnect(2) can connect at any path even withoutrpath or wpath.
Some low-level behaviours required by the DNS resolver described inres_init(3) are permitted. This includes__pledge_open(2) readinghosts(5),protocols(5),resolv.conf(5), andservices(5), and exposing a few networking system calls:socket(2), connect(2),sendto(2), recvfrom(2) which can only operate on the specific socket type SOCK_DNS. The library resolver opens sockets with SOCK_DNS only on port 53, so the kernel can differentiate these operations from regular sockets operations.
This uses the special features of__pledge_open(2) to read required system files to support thegetpwnam(3), getgrnam(3),getgrouplist(3), andinitgroups(3) family of functions, including lookups via theyp(8) protocol for YP and LDAP databases.
Allows sending of file descriptors usingsendmsg(2). File descriptors referring to directories may not be passed.
Allows receiving of file descriptors usingrecvmsg(2). File descriptors referring to directories may not be passed.
Allow MTIOCGET andMTIOCTOP operations against tape drives.
In addition to allowing read-write operations on/dev/tty, this opens up a variety ofioctl(2) requests used by tty devices. If tty is accompanied with rpath,revoke(2) is permitted. Otherwise only the followingioctl(2) requests are permitted:
TIOCSPGRP,TIOCGETA, TIOCGPGRP,TIOCGWINSZ, TIOCSWINSZ,TIOCSBRK, TIOCCDTR,TIOCSETA, TIOCSETAW,TIOCSETAF, TIOCUCNTL
Allows the following process relationship operations:
fork(2), vfork(2), kill(2),getpriority(2),setpriority(2),setrlimit(2),setpgid(2), setsid(2)
Allows a process to callexecve(2). Coupled with the proc promise, this allows a process to fork and execute another program. Ifexecpromises 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.
Allows the use of PROT_EXEC withmmap(2) andmprotect(2).
Allows the setting of system time, via thesettimeofday(2),adjtime(2), andadjfreq(2) system calls.
Allows enough sysctl(2) interfaces to allow inspection of processes operating on the system using programs like ps(1).
Allows enough sysctl(2) interfaces to allow inspection of the system's virtual memory by programs like top(1) andvmstat(8).
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)
Allows a subset of ioctl(2) operations on thepf(4) device:
DIOCADDRULE,DIOCGETSTATUS,DIOCNATLOOK,DIOCRADDTABLES,DIOCRCLRADDRS,DIOCRCLRTABLES,DIOCRCLRTSTATS,DIOCRGETTSTATS,DIOCRSETADDRS,DIOCXBEGIN,DIOCXCOMMIT
Allow inspection of the routing table.
Allow changes to the routing table.
Allows a subset of ioctl(2) operations onaudio(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
Allows a subset of ioctl(2) operations onvideo(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
Allow BIOCGSTATS operation for statistics collection from a bpf(4) device.
Allow unveil(2) to be called.
Rather than killing the process upon violation, indicate error withENOSYS.
Also whenpledge() is called with higher promises orexecpromises, those changes will be ignored and return success. This is useful when a parent enforcesexecpromises but an execve'd child has a different idea.
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.
RETURN VALUES
Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variableerrno is set to indicate the error.
ERRORS
pledge() will fail if:
[EFAULT]
promises or execpromises points outside the process's allocated address space.
[EINVAL]
promises is malformed or contains invalid keywords.
[EPERM]
This process is attempting to increase permissions.
HISTORY
The pledge() system call first appeared inOpenBSD 5.9.