1.\" $OpenBSD: pledge.2,v 1.64 2022/07/17 03:12:55 deraadt 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 2022 $ 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.Fa promises 37or 38.Fa 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.Fa 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.Fa promises 76or 77.Fa 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.Cm audio , 113.Cm bpf , 114.Cm disklabel , 115.Cm drm , 116.Cm inet , 117.Cm pf , 118.Cm route , 119.Cm wroute , 120.Cm tape , 121.Cm tty , 122.Cm video , 123and 124.Cm 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.Fa promises 140and 141.Fa 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.Fa promises 154argument is specified as a string, with space separated keywords: 155.Bl -tag -width "prot_exec" -offset indent 156.It Cm 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 Cm 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 Cm 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 Cm 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 Cm dpath 288A number of system calls are allowed to create special files: 289.Pp 290.Xr mkfifo 2 , 291.Xr mknod 2 292.It Cm 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 Cm 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 Cm mcast 324In combination with 325.Cm inet 326give back functionality to 327.Xr setsockopt 2 328for operating on multicast sockets. 329.It Cm 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 Cm chown 350The 351.Xr chown 2 352family is allowed to change the user or group on a file. 353.It Cm 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 Cm 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 Cm 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 Cm 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, including lookups via the 399.Xr yp 8 400protocol for YP and LDAP databases. 401.It Cm sendfd 402Allows sending of file descriptors using 403.Xr sendmsg 2 . 404File descriptors referring to directories may not be passed. 405.It Cm recvfd 406Allows receiving of file descriptors using 407.Xr recvmsg 2 . 408File descriptors referring to directories may not be passed. 409.It Cm tape 410Allow 411.Dv MTIOCGET 412and 413.Dv MTIOCTOP 414operations against tape drives. 415.It Cm tty 416In addition to allowing read-write operations on 417.Pa /dev/tty , 418this opens up a variety of 419.Xr ioctl 2 420requests used by tty devices. 421If 422.Cm tty 423is accompanied with 424.Cm rpath , 425.Xr revoke 2 426is permitted. 427Otherwise only the following 428.Xr ioctl 2 429requests are permitted: 430.Pp 431.Dv TIOCSPGRP , 432.Dv TIOCGETA , 433.Dv TIOCGPGRP , 434.Dv TIOCGWINSZ , 435.Dv TIOCSWINSZ , 436.Dv TIOCSBRK , 437.Dv TIOCCDTR , 438.Dv TIOCSETA , 439.Dv TIOCSETAW , 440.Dv TIOCSETAF , 441.Dv TIOCUCNTL 442.It Cm proc 443Allows the following process relationship operations: 444.Pp 445.Xr fork 2 , 446.Xr vfork 2 , 447.Xr kill 2 , 448.Xr getpriority 2 , 449.Xr setpriority 2 , 450.Xr setrlimit 2 , 451.Xr setpgid 2 , 452.Xr setsid 2 453.It Cm exec 454Allows a process to call 455.Xr execve 2 . 456Coupled with the 457.Cm proc 458promise, this allows a process to fork and execute another program. 459If 460.Fa execpromises 461has been previously set the new program begins with those promises, 462unless setuid/setgid bits are set in which case execution is blocked with 463.Er EACCES . 464Otherwise the new program starts running without pledge active, 465and hopefully makes a new pledge soon. 466.It Cm prot_exec 467Allows the use of 468.Dv PROT_EXEC 469with 470.Xr mmap 2 471and 472.Xr mprotect 2 . 473.It Cm settime 474Allows the setting of system time, via the 475.Xr settimeofday 2 , 476.Xr adjtime 2 , 477and 478.Xr adjfreq 2 479system calls. 480.It Cm ps 481Allows enough 482.Xr sysctl 2 483interfaces to allow inspection of processes operating on the system using 484programs like 485.Xr ps 1 . 486.It Cm vminfo 487Allows enough 488.Xr sysctl 2 489interfaces to allow inspection of the system's virtual memory by 490programs like 491.Xr top 1 492and 493.Xr vmstat 8 . 494.It Cm id 495Allows the following system calls which can change the rights of a 496process: 497.Pp 498.Xr setuid 2 , 499.Xr seteuid 2 , 500.Xr setreuid 2 , 501.Xr setresuid 2 , 502.Xr setgid 2 , 503.Xr setegid 2 , 504.Xr setregid 2 , 505.Xr setresgid 2 , 506.Xr setgroups 2 , 507.Xr setlogin 2 , 508.Xr setrlimit 2 , 509.Xr getpriority 2 , 510.Xr setpriority 2 , 511.Xr setrtable 2 512.It Cm pf 513Allows a subset of 514.Xr ioctl 2 515operations on the 516.Xr pf 4 517device: 518.Pp 519.Dv DIOCADDRULE , 520.Dv DIOCGETSTATUS , 521.Dv DIOCNATLOOK , 522.Dv DIOCRADDTABLES , 523.Dv DIOCRCLRADDRS , 524.Dv DIOCRCLRTABLES , 525.Dv DIOCRCLRTSTATS , 526.Dv DIOCRGETTSTATS , 527.Dv DIOCRSETADDRS , 528.Dv DIOCXBEGIN , 529.Dv DIOCXCOMMIT 530.It Cm route 531Allow inspection of the routing table. 532.It Cm wroute 533Allow changes to the routing table. 534.It Cm audio 535Allows a subset of 536.Xr ioctl 2 537operations on 538.Xr audio 4 539devices 540(see 541.Xr sio_open 3 542for more information): 543.Pp 544.Dv AUDIO_GETPOS , 545.Dv AUDIO_GETPAR , 546.Dv AUDIO_SETPAR , 547.Dv AUDIO_START , 548.Dv AUDIO_STOP , 549.Dv AUDIO_MIXER_DEVINFO , 550.Dv AUDIO_MIXER_READ , 551.Dv AUDIO_MIXER_WRITE 552.It Cm video 553Allows a subset of 554.Xr ioctl 2 555operations on 556.Xr video 4 557devices: 558.Pp 559.Dv VIDIOC_DQBUF , 560.Dv VIDIOC_ENUM_FMT , 561.Dv VIDIOC_ENUM_FRAMEINTERVALS , 562.Dv VIDIOC_ENUM_FRAMESIZES , 563.Dv VIDIOC_G_CTRL , 564.Dv VIDIOC_G_PARM , 565.Dv VIDIOC_QBUF , 566.Dv VIDIOC_QUERYBUF , 567.Dv VIDIOC_QUERYCAP , 568.Dv VIDIOC_QUERYCTRL , 569.Dv VIDIOC_S_CTRL , 570.Dv VIDIOC_S_FMT , 571.Dv VIDIOC_S_PARM , 572.Dv VIDIOC_STREAMOFF , 573.Dv VIDIOC_STREAMON , 574.Dv VIDIOC_TRY_FMT , 575.Dv VIDIOC_REQBUFS 576.It Cm bpf 577Allow 578.Dv BIOCGSTATS 579operation for statistics collection from a 580.Xr bpf 4 581device. 582.It Cm unveil 583Allow 584.Xr unveil 2 585to be called. 586.It Cm error 587Rather than killing the process upon violation, indicate error with 588.Er ENOSYS . 589.Pp 590Also when 591.Fn pledge 592is called with higher 593.Fa promises 594or 595.Fa execpromises , 596those changes will be ignored and return success. 597This is useful when a parent enforces 598.Fa execpromises 599but an execve'd child has a different idea. 600.El 601.Sh RETURN VALUES 602.Rv -std 603.Sh ERRORS 604.Fn pledge 605will fail if: 606.Bl -tag -width Er 607.It Bq Er EFAULT 608.Fa promises 609or 610.Fa execpromises 611points outside the process's allocated address space. 612.It Bq Er EINVAL 613.Fa promises 614is malformed or contains invalid keywords. 615.It Bq Er EPERM 616This process is attempting to increase permissions. 617.El 618.Sh HISTORY 619The 620.Fn pledge 621system call first appeared in 622.Ox 5.9 . 623