1.\" $OpenBSD: pledge.2,v 1.70 2024/09/17 12:53:15 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: September 17 2024 $ 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, 33networking (and notably separate, DNS resolution). 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 Xr profil 2 : 138Can only disable profiling. 139.It Fn pledge : 140Can only reduce permissions for 141.Fa promises 142and 143.Fa execpromises . 144.It Xr sysctl 2 : 145A small set of read-only operations are allowed, sufficient to 146support: 147.Xr getdomainname 3 , 148.Xr gethostname 3 , 149.Xr getifaddrs 3 , 150.Xr uname 3 , 151and system sensor readings. 152.El 153.Pp 154The 155.Fa promises 156argument is specified as a string, with space separated keywords: 157.Bl -tag -width "prot_exec" -offset indent 158.It Cm stdio 159The following system calls are permitted. 160.Xr sendto 2 161is only permitted if its destination socket address is 162.Dv NULL . 163As a result, all the expected functionalities of libc stdio work. 164.Pp 165.Xr clock_getres 2 , 166.Xr clock_gettime 2 , 167.Xr close 2 , 168.Xr closefrom 2 , 169.Xr dup 2 , 170.Xr dup2 2 , 171.Xr dup3 2 , 172.Xr fchdir 2 , 173.Xr fcntl 2 , 174.Xr fstat 2 , 175.Xr fsync 2 , 176.Xr ftruncate 2 , 177.Xr getdtablecount 2 , 178.Xr getegid 2 , 179.Xr getentropy 2 , 180.Xr geteuid 2 , 181.Xr getgid 2 , 182.Xr getgroups 2 , 183.Xr getitimer 2 , 184.Xr getlogin 2 , 185.Xr getpgid 2 , 186.Xr getpgrp 2 , 187.Xr getpid 2 , 188.Xr getppid 2 , 189.Xr getresgid 2 , 190.Xr getresuid 2 , 191.Xr getrlimit 2 , 192.Xr getrtable 2 , 193.Xr getsid 2 , 194.Xr getthrid 2 , 195.Xr gettimeofday 2 , 196.Xr getuid 2 , 197.Xr issetugid 2 , 198.Xr kevent 2 , 199.Xr kqueue 2 , 200.Xr kqueue1 2 , 201.Xr lseek 2 , 202.Xr madvise 2 , 203.Xr minherit 2 , 204.Xr mmap 2 , 205.Xr mprotect 2 , 206.Xr mquery 2 , 207.Xr munmap 2 , 208.Xr nanosleep 2 , 209.Xr pipe 2 , 210.Xr pipe2 2 , 211.Xr poll 2 , 212.Xr pread 2 , 213.Xr preadv 2 , 214.Xr profil 2 , 215.Xr pwrite 2 , 216.Xr pwritev 2 , 217.Xr read 2 , 218.Xr readv 2 , 219.Xr recvfrom 2 , 220.Xr recvmsg 2 , 221.Xr select 2 , 222.Xr sendmsg 2 , 223.Xr sendsyslog 2 , 224.Xr sendto 2 , 225.Xr setitimer 2 , 226.Xr shutdown 2 , 227.Xr sigaction 2 , 228.Xr sigprocmask 2 , 229.Xr sigreturn 2 , 230.Xr socketpair 2 , 231.Xr umask 2 , 232.Xr wait4 2 , 233.Xr waitid 2 , 234.Xr write 2 , 235.Xr writev 2 236.It Cm rpath 237A number of system calls are allowed if they only cause 238read-only effects on the filesystem, or expose filenames to programs: 239.Pp 240.Xr chdir 2 , 241.Xr getcwd 3 , 242.Xr getdents 2 , 243.Xr openat 2 , 244.Xr fstatat 2 , 245.Xr faccessat 2 , 246.Xr readlinkat 2 , 247.Xr lstat 2 , 248.Xr chmod 2 , 249.Xr fchmod 2 , 250.Xr fchmodat 2 , 251.Xr chflags 2 , 252.Xr chflagsat 2 , 253.Xr chown 2 , 254.Xr fchown 2 , 255.Xr fchownat 2 , 256.Xr fstat 2 , 257.Xr getfsstat 2 258.It Cm wpath 259A number of system calls are allowed and may cause 260write-effects on the filesystem: 261.Pp 262.Xr getcwd 3 , 263.Xr openat 2 , 264.Xr fstatat 2 , 265.Xr faccessat 2 , 266.Xr readlinkat 2 , 267.Xr lstat 2 , 268.Xr chmod 2 , 269.Xr fchmod 2 , 270.Xr fchmodat 2 , 271.Xr chflags 2 , 272.Xr chflagsat 2 , 273.Xr chown 2 , 274.Xr fchown 2 , 275.Xr fchownat 2 , 276.Xr fstat 2 277.It Cm cpath 278A number of system calls and sub-modes are allowed, which may 279create new files or directories in the filesystem: 280.Pp 281.Xr rename 2 , 282.Xr renameat 2 , 283.Xr link 2 , 284.Xr linkat 2 , 285.Xr symlink 2 , 286.Xr symlinkat 2 , 287.Xr unlink 2 , 288.Xr unlinkat 2 , 289.Xr mkdir 2 , 290.Xr mkdirat 2 , 291.Xr rmdir 2 292.It Cm dpath 293A number of system calls are allowed to create special files: 294.Pp 295.Xr mkfifo 2 , 296.Xr mknod 2 297.It Cm tmppath 298A number of system calls are allowed to do operations in the 299.Pa /tmp 300directory, including create, read, or write: 301.Pp 302.Xr lstat 2 , 303.Xr chmod 2 , 304.Xr chflags 2 , 305.Xr chown 2 , 306.Xr unlink 2 , 307.Xr fstat 2 308.It Cm inet 309The following system calls are allowed to operate in the 310.Dv AF_INET 311and 312.Dv AF_INET6 313domains 314(though 315.Xr setsockopt 2 316has been substantially reduced in functionality): 317.Pp 318.Xr socket 2 , 319.Xr listen 2 , 320.Xr bind 2 , 321.Xr connect 2 , 322.Xr accept4 2 , 323.Xr accept 2 , 324.Xr getpeername 2 , 325.Xr getsockname 2 , 326.Xr setsockopt 2 , 327.Xr getsockopt 2 328.It Cm mcast 329In combination with 330.Cm inet 331give back functionality to 332.Xr setsockopt 2 333for operating on multicast sockets. 334.It Cm fattr 335The following system calls are allowed to make explicit changes 336to fields in 337.Vt struct stat 338relating to a file: 339.Pp 340.Xr utimes 2 , 341.Xr futimes 2 , 342.Xr utimensat 2 , 343.Xr futimens 2 , 344.Xr chmod 2 , 345.Xr fchmod 2 , 346.Xr fchmodat 2 , 347.Xr chflags 2 , 348.Xr chflagsat 2 , 349.Xr chown 2 , 350.Xr fchownat 2 , 351.Xr lchown 2 , 352.Xr fchown 2 , 353.Xr utimes 2 354.It Cm chown 355The 356.Xr chown 2 357family is allowed to change the user or group on a file. 358.It Cm flock 359File locking via 360.Xr fcntl 2 , 361.Xr flock 2 , 362.Xr lockf 3 , 363and 364.Xr open 2 365is allowed. 366No distinction is made between shared and exclusive locks. 367This promise is required for unlock as well as lock. 368.It Cm unix 369The following system calls are allowed to operate in the 370.Dv AF_UNIX 371domain: 372.Pp 373.Xr socket 2 , 374.Xr listen 2 , 375.Xr bind 2 , 376.Xr connect 2 , 377.Xr accept4 2 , 378.Xr accept 2 , 379.Xr getpeername 2 , 380.Xr getsockname 2 , 381.Xr setsockopt 2 , 382.Xr getsockopt 2 383.It Cm dns 384Subsequent to a successful 385.Xr open 2 386of 387.Pa /etc/resolv.conf , 388a few system calls become able to allow DNS network transactions: 389.Pp 390.Xr sendto 2 , 391.Xr recvfrom 2 , 392.Xr socket 2 , 393.Xr connect 2 394.It Cm getpw 395This allows read-only opening of files in 396.Pa /etc 397for the 398.Xr getpwnam 3 , 399.Xr getgrnam 3 , 400.Xr getgrouplist 3 , 401and 402.Xr initgroups 3 403family of functions, including lookups via the 404.Xr yp 8 405protocol for YP and LDAP databases. 406.It Cm sendfd 407Allows sending of file descriptors using 408.Xr sendmsg 2 . 409File descriptors referring to directories may not be passed. 410.It Cm recvfd 411Allows receiving of file descriptors using 412.Xr recvmsg 2 . 413File descriptors referring to directories may not be passed. 414.It Cm tape 415Allow 416.Dv MTIOCGET 417and 418.Dv MTIOCTOP 419operations against tape drives. 420.It Cm tty 421In addition to allowing read-write operations on 422.Pa /dev/tty , 423this opens up a variety of 424.Xr ioctl 2 425requests used by tty devices. 426If 427.Cm tty 428is accompanied with 429.Cm rpath , 430.Xr revoke 2 431is permitted. 432Otherwise only the following 433.Xr ioctl 2 434requests are permitted: 435.Pp 436.Dv TIOCSPGRP , 437.Dv TIOCGETA , 438.Dv TIOCGPGRP , 439.Dv TIOCGWINSZ , 440.Dv TIOCSWINSZ , 441.Dv TIOCSBRK , 442.Dv TIOCCDTR , 443.Dv TIOCSETA , 444.Dv TIOCSETAW , 445.Dv TIOCSETAF , 446.Dv TIOCUCNTL 447.It Cm proc 448Allows the following process relationship operations: 449.Pp 450.Xr fork 2 , 451.Xr vfork 2 , 452.Xr kill 2 , 453.Xr getpriority 2 , 454.Xr setpriority 2 , 455.Xr setrlimit 2 , 456.Xr setpgid 2 , 457.Xr setsid 2 458.It Cm exec 459Allows a process to call 460.Xr execve 2 . 461Coupled with the 462.Cm proc 463promise, this allows a process to fork and execute another program. 464If 465.Fa execpromises 466has been previously set the new program begins with those promises, 467unless setuid/setgid bits are set in which case execution is blocked with 468.Er EACCES . 469Otherwise the new program starts running without pledge active, 470and hopefully makes a new pledge soon. 471.It Cm prot_exec 472Allows the use of 473.Dv PROT_EXEC 474with 475.Xr mmap 2 476and 477.Xr mprotect 2 . 478.It Cm settime 479Allows the setting of system time, via the 480.Xr settimeofday 2 , 481.Xr adjtime 2 , 482and 483.Xr adjfreq 2 484system calls. 485.It Cm ps 486Allows enough 487.Xr sysctl 2 488interfaces to allow inspection of processes operating on the system using 489programs like 490.Xr ps 1 . 491.It Cm vminfo 492Allows enough 493.Xr sysctl 2 494interfaces to allow inspection of the system's virtual memory by 495programs like 496.Xr top 1 497and 498.Xr vmstat 8 . 499.It Cm id 500Allows the following system calls which can change the rights of a 501process: 502.Pp 503.Xr setuid 2 , 504.Xr seteuid 2 , 505.Xr setreuid 2 , 506.Xr setresuid 2 , 507.Xr setgid 2 , 508.Xr setegid 2 , 509.Xr setregid 2 , 510.Xr setresgid 2 , 511.Xr setgroups 2 , 512.Xr setlogin 2 , 513.Xr setrlimit 2 , 514.Xr getpriority 2 , 515.Xr setpriority 2 , 516.Xr setrtable 2 517.It Cm pf 518Allows a subset of 519.Xr ioctl 2 520operations on the 521.Xr pf 4 522device: 523.Pp 524.Dv DIOCADDRULE , 525.Dv DIOCGETSTATUS , 526.Dv DIOCNATLOOK , 527.Dv DIOCRADDTABLES , 528.Dv DIOCRCLRADDRS , 529.Dv DIOCRCLRTABLES , 530.Dv DIOCRCLRTSTATS , 531.Dv DIOCRGETTSTATS , 532.Dv DIOCRSETADDRS , 533.Dv DIOCXBEGIN , 534.Dv DIOCXCOMMIT 535.It Cm route 536Allow inspection of the routing table. 537.It Cm wroute 538Allow changes to the routing table. 539.It Cm audio 540Allows a subset of 541.Xr ioctl 2 542operations on 543.Xr audio 4 544devices 545(see 546.Xr sio_open 3 547for more information): 548.Pp 549.Dv AUDIO_GETPOS , 550.Dv AUDIO_GETPAR , 551.Dv AUDIO_SETPAR , 552.Dv AUDIO_START , 553.Dv AUDIO_STOP , 554.Dv AUDIO_MIXER_DEVINFO , 555.Dv AUDIO_MIXER_READ , 556.Dv AUDIO_MIXER_WRITE 557.It Cm video 558Allows a subset of 559.Xr ioctl 2 560operations on 561.Xr video 4 562devices: 563.Pp 564.Dv VIDIOC_DQBUF , 565.Dv VIDIOC_ENUM_FMT , 566.Dv VIDIOC_ENUM_FRAMEINTERVALS , 567.Dv VIDIOC_ENUM_FRAMESIZES , 568.Dv VIDIOC_G_CTRL , 569.Dv VIDIOC_G_PARM , 570.Dv VIDIOC_QBUF , 571.Dv VIDIOC_QUERYBUF , 572.Dv VIDIOC_QUERYCAP , 573.Dv VIDIOC_QUERYCTRL , 574.Dv VIDIOC_S_CTRL , 575.Dv VIDIOC_S_FMT , 576.Dv VIDIOC_S_PARM , 577.Dv VIDIOC_STREAMOFF , 578.Dv VIDIOC_STREAMON , 579.Dv VIDIOC_TRY_FMT , 580.Dv VIDIOC_REQBUFS 581.It Cm bpf 582Allow 583.Dv BIOCGSTATS 584operation for statistics collection from a 585.Xr bpf 4 586device. 587.It Cm unveil 588Allow 589.Xr unveil 2 590to be called. 591.It Cm error 592Rather than killing the process upon violation, indicate error with 593.Er ENOSYS . 594.Pp 595Also when 596.Fn pledge 597is called with higher 598.Fa promises 599or 600.Fa execpromises , 601those changes will be ignored and return success. 602This is useful when a parent enforces 603.Fa execpromises 604but an execve'd child has a different idea. 605.El 606.Sh RETURN VALUES 607.Rv -std 608.Sh ERRORS 609.Fn pledge 610will fail if: 611.Bl -tag -width Er 612.It Bq Er EFAULT 613.Fa promises 614or 615.Fa execpromises 616points outside the process's allocated address space. 617.It Bq Er EINVAL 618.Fa promises 619is malformed or contains invalid keywords. 620.It Bq Er EPERM 621This process is attempting to increase permissions. 622.El 623.Sh HISTORY 624The 625.Fn pledge 626system call first appeared in 627.Ox 5.9 . 628