1.\" $OpenBSD: pledge.2,v 1.60 2020/07/17 16:40:26 jmc Exp $ 2.\" 3.\" Copyright (c) 2015 Nicholas Marriott <nicm@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 17 2020 $ 18.Dt PLEDGE 2 19.Os 20.Sh NAME 21.Nm pledge 22.Nd restrict system operations 23.Sh SYNOPSIS 24.In unistd.h 25.Ft int 26.Fn pledge "const char *promises" "const char *execpromises" 27.Sh DESCRIPTION 28The 29.Fn pledge 30system call forces the current process into a restricted-service operating mode. 31A few subsets are available, roughly described as computation, memory 32management, read-write operations on file descriptors, opening of files, 33and networking. 34In general, these modes were selected by studying the operation 35of many programs using libc and other such interfaces, and setting 36.Ar promises 37or 38.Ar execpromises . 39.Pp 40Use of 41.Fn pledge 42in an application will require at least some study and understanding 43of the interfaces called. 44Subsequent calls to 45.Fn pledge 46can reduce the abilities further, but abilities can never be regained. 47.Pp 48A process which attempts a restricted operation is killed with an uncatchable 49.Dv SIGABRT , 50delivering a core file if possible. 51A process currently running with pledge has state 52.Sq p 53in 54.Xr ps 1 55output; a process that was terminated due to a pledge violation 56is accounted by 57.Xr lastcomm 1 58with the 59.Sq P 60flag. 61.Pp 62A 63.Ar promises 64value of 65.Qq \& 66restricts the process to the 67.Xr _exit 2 68system call. 69This can be used for pure computation operating on memory shared 70with another process. 71.Pp 72Passing 73.Dv NULL 74to 75.Ar promises 76or 77.Ar execpromises 78specifies to not change the current value. 79.Pp 80Some system calls, when allowed, have restrictions applied to them: 81.Bl -ohang -offset indent 82.It Xr access 2 : 83May check for existence of 84.Pa /etc/localtime . 85.It Xr adjtime 2 : 86Read-only, for 87.Xr ntpd 8 . 88.It Xo 89.Xr chmod 2 , 90.Xr fchmod 2 , 91.Xr fchmodat 2 , 92.Xr chown 2 , 93.Xr lchown 2 , 94.Xr fchown 2 , 95.Xr fchownat 2 , 96.Xr mkfifo 2 , 97and 98.Xr mknod 2 : 99.Xc 100Setuid/setgid/sticky bits are ignored. 101The user or group cannot be changed on a file. 102.It Xr ioctl 2 : 103Only the 104.Dv FIONREAD , 105.Dv FIONBIO , 106.Dv FIOCLEX , 107and 108.Dv FIONCLEX 109operations are allowed by default. 110Various ioctl requests are allowed against specific file descriptors 111based upon the requests 112.Va audio , 113.Va bpf , 114.Va disklabel , 115.Va drm , 116.Va inet , 117.Va pf , 118.Va route , 119.Va wroute , 120.Va tape , 121.Va tty , 122.Va video , 123and 124.Va vmm . 125.It Xo 126.Xr mmap 2 127and 128.Xr mprotect 2 : 129.Xc 130.Dv PROT_EXEC 131isn't allowed. 132.It Xr open 2 : 133May open 134.Pa /etc/localtime 135and any files below 136.Pa /usr/share/zoneinfo . 137.It Fn pledge : 138Can only reduce permissions for 139.Ar promises 140and 141.Ar execpromises . 142.It Xr sysctl 2 : 143A small set of read-only operations are allowed, sufficient to 144support: 145.Xr getdomainname 3 , 146.Xr gethostname 3 , 147.Xr getifaddrs 3 , 148.Xr uname 3 , 149and system sensor readings. 150.El 151.Pp 152The 153.Ar promises 154argument is specified as a string, with space separated keywords: 155.Bl -tag -width "prot_exec" -offset indent 156.It Va stdio 157The following system calls are permitted. 158.Xr sendto 2 159is only permitted if its destination socket address is 160.Dv NULL . 161As a result, all the expected functionalities of libc stdio work. 162.Pp 163.Xr clock_getres 2 , 164.Xr clock_gettime 2 , 165.Xr close 2 , 166.Xr closefrom 2 , 167.Xr dup 2 , 168.Xr dup2 2 , 169.Xr dup3 2 , 170.Xr fchdir 2 , 171.Xr fcntl 2 , 172.Xr fstat 2 , 173.Xr fsync 2 , 174.Xr ftruncate 2 , 175.Xr getdents 2 , 176.Xr getdtablecount 2 , 177.Xr getegid 2 , 178.Xr getentropy 2 , 179.Xr geteuid 2 , 180.Xr getgid 2 , 181.Xr getgroups 2 , 182.Xr getitimer 2 , 183.Xr getlogin 2 , 184.Xr getpgid 2 , 185.Xr getpgrp 2 , 186.Xr getpid 2 , 187.Xr getppid 2 , 188.Xr getresgid 2 , 189.Xr getresuid 2 , 190.Xr getrlimit 2 , 191.Xr getrtable 2 , 192.Xr getsid 2 , 193.Xr getthrid 2 , 194.Xr gettimeofday 2 , 195.Xr getuid 2 , 196.Xr issetugid 2 , 197.Xr kevent 2 , 198.Xr kqueue 2 , 199.Xr lseek 2 , 200.Xr madvise 2 , 201.Xr minherit 2 , 202.Xr mmap 2 , 203.Xr mprotect 2 , 204.Xr mquery 2 , 205.Xr munmap 2 , 206.Xr nanosleep 2 , 207.Xr pipe 2 , 208.Xr pipe2 2 , 209.Xr poll 2 , 210.Xr pread 2 , 211.Xr preadv 2 , 212.Xr pwrite 2 , 213.Xr pwritev 2 , 214.Xr read 2 , 215.Xr readv 2 , 216.Xr recvfrom 2 , 217.Xr recvmsg 2 , 218.Xr select 2 , 219.Xr sendmsg 2 , 220.Xr sendsyslog 2 , 221.Xr sendto 2 , 222.Xr setitimer 2 , 223.Xr shutdown 2 , 224.Xr sigaction 2 , 225.Xr sigprocmask 2 , 226.Xr sigreturn 2 , 227.Xr socketpair 2 , 228.Xr umask 2 , 229.Xr wait4 2 , 230.Xr write 2 , 231.Xr writev 2 232.It Va rpath 233A number of system calls are allowed if they only cause 234read-only effects on the filesystem: 235.Pp 236.Xr chdir 2 , 237.Xr getcwd 3 , 238.Xr openat 2 , 239.Xr fstatat 2 , 240.Xr faccessat 2 , 241.Xr readlinkat 2 , 242.Xr lstat 2 , 243.Xr chmod 2 , 244.Xr fchmod 2 , 245.Xr fchmodat 2 , 246.Xr chflags 2 , 247.Xr chflagsat 2 , 248.Xr chown 2 , 249.Xr fchown 2 , 250.Xr fchownat 2 , 251.Xr fstat 2 , 252.Xr getfsstat 2 253.It Va wpath 254A number of system calls are allowed and may cause 255write-effects on the filesystem: 256.Pp 257.Xr getcwd 3 , 258.Xr openat 2 , 259.Xr fstatat 2 , 260.Xr faccessat 2 , 261.Xr readlinkat 2 , 262.Xr lstat 2 , 263.Xr chmod 2 , 264.Xr fchmod 2 , 265.Xr fchmodat 2 , 266.Xr chflags 2 , 267.Xr chflagsat 2 , 268.Xr chown 2 , 269.Xr fchown 2 , 270.Xr fchownat 2 , 271.Xr fstat 2 272.It Va cpath 273A number of system calls and sub-modes are allowed, which may 274create new files or directories in the filesystem: 275.Pp 276.Xr rename 2 , 277.Xr renameat 2 , 278.Xr link 2 , 279.Xr linkat 2 , 280.Xr symlink 2 , 281.Xr symlinkat 2 , 282.Xr unlink 2 , 283.Xr unlinkat 2 , 284.Xr mkdir 2 , 285.Xr mkdirat 2 , 286.Xr rmdir 2 287.It Va dpath 288A number of system calls are allowed to create special files: 289.Pp 290.Xr mkfifo 2 , 291.Xr mknod 2 292.It Va tmppath 293A number of system calls are allowed to do operations in the 294.Pa /tmp 295directory, including create, read, or write: 296.Pp 297.Xr lstat 2 , 298.Xr chmod 2 , 299.Xr chflags 2 , 300.Xr chown 2 , 301.Xr unlink 2 , 302.Xr fstat 2 303.It Va inet 304The following system calls are allowed to operate in the 305.Dv AF_INET 306and 307.Dv AF_INET6 308domains 309(though 310.Xr setsockopt 2 311has been substantially reduced in functionality): 312.Pp 313.Xr socket 2 , 314.Xr listen 2 , 315.Xr bind 2 , 316.Xr connect 2 , 317.Xr accept4 2 , 318.Xr accept 2 , 319.Xr getpeername 2 , 320.Xr getsockname 2 , 321.Xr setsockopt 2 , 322.Xr getsockopt 2 323.It Va mcast 324In combination with 325.Va inet 326give back functionality to 327.Xr setsockopt 2 328for operating on multicast sockets. 329.It Va fattr 330The following system calls are allowed to make explicit changes 331to fields in 332.Vt struct stat 333relating to a file: 334.Pp 335.Xr utimes 2 , 336.Xr futimes 2 , 337.Xr utimensat 2 , 338.Xr futimens 2 , 339.Xr chmod 2 , 340.Xr fchmod 2 , 341.Xr fchmodat 2 , 342.Xr chflags 2 , 343.Xr chflagsat 2 , 344.Xr chown 2 , 345.Xr fchownat 2 , 346.Xr lchown 2 , 347.Xr fchown 2 , 348.Xr utimes 2 349.It Va chown 350The 351.Xr chown 2 352family is allowed to change the user or group on a file. 353.It Va flock 354File locking via 355.Xr fcntl 2 , 356.Xr flock 2 , 357.Xr lockf 3 , 358and 359.Xr open 2 360is allowed. 361No distinction is made between shared and exclusive locks. 362This promise is required for unlock as well as lock. 363.It Va unix 364The following system calls are allowed to operate in the 365.Dv AF_UNIX 366domain: 367.Pp 368.Xr socket 2 , 369.Xr listen 2 , 370.Xr bind 2 , 371.Xr connect 2 , 372.Xr accept4 2 , 373.Xr accept 2 , 374.Xr getpeername 2 , 375.Xr getsockname 2 , 376.Xr setsockopt 2 , 377.Xr getsockopt 2 378.It Va dns 379Subsequent to a successful 380.Xr open 2 381of 382.Pa /etc/resolv.conf , 383a few system calls become able to allow DNS network transactions: 384.Pp 385.Xr sendto 2 , 386.Xr recvfrom 2 , 387.Xr socket 2 , 388.Xr connect 2 389.It Va getpw 390This allows read-only opening of files in 391.Pa /etc 392for the 393.Xr getpwnam 3 , 394.Xr getgrnam 3 , 395.Xr getgrouplist 3 , 396and 397.Xr initgroups 3 398family of functions. 399They may also need to operate in a 400.Xr yp 8 401environment, so a successful 402.Xr open 2 403of 404.Pa /var/run/ypbind.lock 405enables 406.Va inet 407operations. 408.It Va sendfd 409Allows sending of file descriptors using 410.Xr sendmsg 2 . 411File descriptors referring to directories may not be passed. 412.It Va recvfd 413Allows receiving of file descriptors using 414.Xr recvmsg 2 . 415File descriptors referring to directories may not be passed. 416.It Va tape 417Allow 418.Dv MTIOCGET 419and 420.Dv MTIOCTOP 421operations against tape drives. 422.It Va tty 423In addition to allowing read-write operations on 424.Pa /dev/tty , 425this opens up a variety of 426.Xr ioctl 2 427requests used by tty devices. 428If 429.Va tty 430is accompanied with 431.Va rpath , 432.Xr revoke 2 433is permitted. 434Otherwise only the following 435.Xr ioctl 2 436requests are permitted: 437.Pp 438.Dv TIOCSPGRP , 439.Dv TIOCGETA , 440.Dv TIOCGPGRP , 441.Dv TIOCGWINSZ , 442.Dv TIOCSWINSZ , 443.Dv TIOCSBRK , 444.Dv TIOCCDTR , 445.Dv TIOCSETA , 446.Dv TIOCSETAW , 447.Dv TIOCSETAF , 448.Dv TIOCUCNTL 449.It Va proc 450Allows the following process relationship operations: 451.Pp 452.Xr fork 2 , 453.Xr vfork 2 , 454.Xr kill 2 , 455.Xr getpriority 2 , 456.Xr setpriority 2 , 457.Xr setrlimit 2 , 458.Xr setpgid 2 , 459.Xr setsid 2 460.It Va exec 461Allows a process to call 462.Xr execve 2 . 463Coupled with the 464.Va proc 465promise, this allows a process to fork and execute another program. 466If 467.Ar execpromises 468has been previously set the new program begins with those promises, 469unless setuid/setgid bits are set in which case execution is blocked with 470.Er EACCES . 471Otherwise the new program starts running without pledge active, 472and hopefully makes a new pledge soon. 473.It Va prot_exec 474Allows the use of 475.Dv PROT_EXEC 476with 477.Xr mmap 2 478and 479.Xr mprotect 2 . 480.It Va settime 481Allows the setting of system time, via the 482.Xr settimeofday 2 , 483.Xr adjtime 2 , 484and 485.Xr adjfreq 2 486system calls. 487.It Va ps 488Allows enough 489.Xr sysctl 2 490interfaces to allow inspection of processes operating on the system using 491programs like 492.Xr ps 1 . 493.It Va vminfo 494Allows enough 495.Xr sysctl 2 496interfaces to allow inspection of the system's virtual memory by 497programs like 498.Xr top 1 499and 500.Xr vmstat 8 . 501.It Va id 502Allows the following system calls which can change the rights of a 503process: 504.Pp 505.Xr setuid 2 , 506.Xr seteuid 2 , 507.Xr setreuid 2 , 508.Xr setresuid 2 , 509.Xr setgid 2 , 510.Xr setegid 2 , 511.Xr setregid 2 , 512.Xr setresgid 2 , 513.Xr setgroups 2 , 514.Xr setlogin 2 , 515.Xr setrlimit 2 , 516.Xr getpriority 2 , 517.Xr setpriority 2 518.It Va pf 519Allows a subset of 520.Xr ioctl 2 521operations on the 522.Xr pf 4 523device: 524.Pp 525.Dv DIOCADDRULE , 526.Dv DIOCGETSTATUS , 527.Dv DIOCNATLOOK , 528.Dv DIOCRADDTABLES , 529.Dv DIOCRCLRADDRS , 530.Dv DIOCRCLRTABLES , 531.Dv DIOCRCLRTSTATS , 532.Dv DIOCRGETTSTATS , 533.Dv DIOCRSETADDRS , 534.Dv DIOCXBEGIN , 535.Dv DIOCXCOMMIT 536.It Va route 537Allow inspection of the routing table. 538.It Va wroute 539Allow changes to the routing table. 540.It Va audio 541Allows a subset of 542.Xr ioctl 2 543operations on 544.Xr audio 4 545devices 546(see 547.Xr sio_open 3 548for more information): 549.Pp 550.Dv AUDIO_GETPOS , 551.Dv AUDIO_GETPAR , 552.Dv AUDIO_SETPAR , 553.Dv AUDIO_START , 554.Dv AUDIO_STOP , 555.Dv AUDIO_MIXER_DEVINFO , 556.Dv AUDIO_MIXER_READ , 557.Dv AUDIO_MIXER_WRITE 558.It Va video 559Allows a subset of 560.Xr ioctl 2 561operations on 562.Xr video 4 563devices: 564.Pp 565.Dv VIDIOC_DQBUF , 566.Dv VIDIOC_ENUM_FMT , 567.Dv VIDIOC_ENUM_FRAMEINTERVALS , 568.Dv VIDIOC_ENUM_FRAMESIZES , 569.Dv VIDIOC_G_CTRL , 570.Dv VIDIOC_G_PARM , 571.Dv VIDIOC_QBUF , 572.Dv VIDIOC_QUERYBUF , 573.Dv VIDIOC_QUERYCAP , 574.Dv VIDIOC_QUERYCTRL , 575.Dv VIDIOC_S_CTRL , 576.Dv VIDIOC_S_FMT , 577.Dv VIDIOC_S_PARM , 578.Dv VIDIOC_STREAMOFF , 579.Dv VIDIOC_STREAMON , 580.Dv VIDIOC_TRY_FMT , 581.Dv VIDIOC_REQBUFS 582.It Va bpf 583Allow 584.Dv BIOCGSTATS 585operation for statistics collection from a 586.Xr bpf 4 587device. 588.It Va unveil 589Allow 590.Xr unveil 2 591to be called. 592.It Va error 593Rather than killing the process upon violation, indicate error with 594.Er ENOSYS . 595.Pp 596Also when 597.Fn pledge 598is called with higher 599.Ar promises 600or 601.Ar execpromises , 602those changes will be ignored and return success. 603This is useful when a parent enforces 604.Ar execpromises 605but an execve'd child has a different idea. 606.El 607.Sh RETURN VALUES 608.Rv -std 609.Sh ERRORS 610.Fn pledge 611will fail if: 612.Bl -tag -width Er 613.It Bq Er EFAULT 614.Ar promises 615or 616.Ar execpromises 617points outside the process's allocated address space. 618.It Bq Er EINVAL 619.Ar promises 620is malformed or contains invalid keywords. 621.It Bq Er EPERM 622This process is attempting to increase permissions. 623.El 624.Sh HISTORY 625The 626.Fn pledge 627system call first appeared in 628.Ox 5.9 . 629