PLEDGE(2)

NAME
pledge - restrict system operations

SYNOPSIS
#include <unistd.h>
int
pledge(const char *promises, const char *paths[]);

DESCRIPTION
The current process is forced 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. In general, these modes were selected by studying the operation of many programs using libc and other such interfaces, and setting promises or paths.

Use of pledge() in an application will require at least some study and understanding of the interfaces called. Subsequent calls to pledge() 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 promises 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 promises or paths specifies to not change the current value.

Some system calls, when allowed, have restrictions applied to them:

access(2)
    May check for existence of /etc/localtime.

adjtime(2)
    Read-only, for ntpd(8).

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 audio, bpf, disklabel, drm, inet, pf, route, tape, tty, and vmm.

chmod(2)
fchmod(2)
fchmodat(2)
chown(2)
lchown(2)
fchown(2)
fchownat(2)
mkfifo(2)
mknod(2)
    Setuid/setgid/sticky bits are ignored. The user or group cannot be changed on a file.

mmap(2)
mprotect(2)
    PROT_EXEC isn't allowed.

open(2)
    May open /etc/localtime and any files below /usr/share/zoneinfo.

readlink(2)
    May operate on /etc/malloc.conf.

sysctl(3)
    A small set of read-only operations are allowed, sufficient to support: getdomainname(3), gethostname(3), getifaddrs(3), uname(3), system sensor readings.

pledge()
    Can only reduce permissions; can only set a list of paths once.

The promises is specified as a string, with space separated keywords:

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:

    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), getdents(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), getuid(2), issetugid(2), kevent(2), kqueue(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), 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), write(2), writev(2).

    Note that sendto(2) is only permitted if its destination socket address is NULL. As a result, all the expected functionalities of libc stdio work.

rpath
    A number of system calls are allowed if they only cause read-only effects on the filesystem:

    chdir(2), 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), getfsstat(2).

wpath
    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).

cpath
    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).

dpath
    A number of system calls are allowed to create special files:

    mkfifo(2), mknod(2).

tmppath
    A number of system calls are allowed to do operations in the /tmp directory, including create, read, or write:

    lstat(2), chmod(2), chflags(2), chown(2), unlink(2), fstat(2).

inet
    The following system calls are allowed to operate in the AF_INET and AF_INET6 domains:

    socket(2), listen(2), bind(2), connect(2), accept4(2), accept(2), getpeername(2), getsockname(2), setsockopt(2), getsockopt(2).

    setsockopt(2) has been reduced in functionality substantially.

mcast
    In combination with inet give back functionality to setsockopt(2) for operating on multicast sockets.

fattr
    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).

chown
    The chown(2) family is allowed to change the user or group on a file.

flock
    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.

unix
    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).

dns Subsequent to a successful open(2) of /etc/resolv.conf, a few system calls become able to allow DNS network transactions:

    sendto(2), recvfrom(2), socket(2), connect(2).

getpw
    This allows read-only opening of files in /etc for the getpwnam(3), getgrnam(3), getgrouplist(3), and initgroups(3) family of functions. They may also need to operate in a yp(8) environment, so a successful open(2) of /var/run/ypbind.lock enables inet operations.

sendfd
    Allows sending of file descriptors using sendmsg(2). File descriptors referring to directories may not be passed.

recvfd
    Allows receiving of file descriptors using recvmsg(2). File descriptors referring to directories may not be passed.

tape
    Allow MTIOCGET and MTIOCTOP operations against tape drives.

tty In addition to allowing read-write operations on /dev/tty, this opens up a variety of ioctl(2) requests used by tty devices. The following ioctl(2) requests are permitted: TIOCSPGRP, TIOCGETA, TIOCGPGRP, TIOCGWINSZ, TIOCSWINSZ, TIOCSBRK, TIOCCDTR, TIOCSETA, TIOCSETAW and TIOCSETAF.

    If tty is accompanied with rpath, revoke(2) is permitted.

proc
    Allows the following process relationship operations:

    fork(2), vfork(2), kill(2), getpriority(2), setpriority(2), setrlimit(2), setpgid(2), setsid(2).

exec
    Allows a process to call execve(2). Coupled with the proc promise, this allows a process to fork and execute another program. The new program starts running without pledge active and hopefully makes a new pledge().

prot_exec
    Allows the use of PROT_EXEC with mmap(2) and mprotect(2).

settime
    Allows the setting of system time, via the settimeofday(2), adjtime(2), and adjfreq(2) system calls.

ps  Allows enough sysctl(3) interfaces to allow inspection of processes operating on the system using programs like ps(1).

vminfo
    Allows enough sysctl(3) interfaces to allow inspection of the system's virtual memory by programs like top(1) and vmstat(8).

id  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).

pf  Allows a subset of ioctl(2) operations on the pf(4) device:

    DIOCADDRULE, DIOCGETSTATUS, DIOCNATLOOK, DIOCRADDTABLES, DIOCRCLRADDRS, DIOCRCLRTABLES, DIOCRCLRTSTATS, DIOCRGETTSTATS, DIOCRSETADDRS, DIOCXBEGIN, DIOCXCOMMIT.

audio
    Allows a subset of ioctl(2) operations on audio(4) devices:

    AUDIO_GETPOS, AUDIO_GETPAR, AUDIO_SETPAR, AUDIO_START, AUDIO_STOP.

    See sio_open(3) for more information on using the sndio API in combination with pledge().

bpf Allow BIOCGSTATS operation for statistics collection from a bpf device.

A whitelist of permitted paths may be provided in paths. All other paths will return ENOENT. At least one promise is required to be pledged in order to activate a whitelist.

RETURN VALUES

ERRORS
pledge() will fail if:

[EFAULT]
    paths or one of its elements, or promises points outside the process's allocated address space.

[EINVAL]
    promises is malformed or contains invalid keywords.

[ENAMETOOLONG]
    An element of paths is too large, prepending cwd to it would exceed PATH_MAX bytes, or promises is too long.

[EPERM]
    This process is attempting to increase permissions.

[E2BIG]
    The paths array is too large, or the total number of bytes exceeds a system-imposed limit. The limit in the system as released is 262144 bytes (ARG_MAX).

HISTORY
The pledge() system call first appeared in OpenBSD 5.9.

BUGS
The path whitelist feature is not available at this time.