1.\" $OpenBSD: pledge.2,v 1.36 2016/09/13 17:02:12 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 13 2016 $ 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 *paths[]" 27.Sh DESCRIPTION 28The current process is forced into a restricted-service operating mode. 29A few subsets are available, roughly described as computation, memory 30management, read-write operations on file descriptors, opening of files, 31networking. 32In general, these modes were selected by studying the operation 33of many programs using libc and other such interfaces, and setting 34.Ar promises 35or 36.Ar paths . 37.Pp 38Use of 39.Fn pledge 40in an application will require at least some study and understanding 41of the interfaces called. 42Subsequent calls to 43.Fn pledge 44can reduce the abilities further, but abilities can never be regained. 45.Pp 46A process which attempts a restricted operation is killed with an uncatchable 47.Dv SIGABRT , 48delivering a core file if possible. 49.Pp 50A 51.Fa promises 52value of "" restricts the process to the 53.Xr _exit 2 54system call. 55This can be used for pure computation operating on memory shared 56with another process. 57.Pp 58Passing 59.Dv NULL 60to 61.Fa promises 62or 63.Fa paths 64specifies to not change the current value. 65.Pp 66Some system calls, when allowed, have restrictions applied to them: 67.Pp 68.Bl -tag -width "readlink(2)" -offset indent -compact 69.It Xr access 2 70May check for existence of 71.Pa /etc/localtime . 72.Pp 73.It Xr adjtime 2 74Read-only, for 75.Xr ntpd 8 . 76.Pp 77.It Xr ioctl 2 78Only the 79.Dv FIONREAD 80and 81.Dv FIONBIO 82operations are allowed by default. 83Use of the "tty" and "ioctl" promises receive more ioctl requests. 84.Pp 85.It Xr chmod 2 86.It Xr fchmod 2 87.It Xr fchmodat 2 88.It Xr chown 2 89.It Xr lchown 2 90.It Xr fchown 2 91.It Xr fchownat 2 92.It Xr mkfifo 2 93.It Xr mknod 2 94Setuid/setgid/sticky bits are ignored. 95The user or group cannot be changed on a file. 96.Pp 97.It Xr mmap 2 98.It Xr mprotect 2 99.Dv PROT_EXEC 100isn't allowed. 101.Pp 102.It Xr open 2 103May open 104.Pa /etc/localtime 105and any files below 106.Pa /usr/share/zoneinfo . 107.Pp 108.It Xr readlink 2 109May operate on 110.Pa /etc/malloc.conf . 111.Pp 112.It Xr sysctl 3 113A small set of read-only operations are allowed, sufficient to 114support: 115.Xr getdomainname 3 , 116.Xr gethostname 3 , 117.Xr getifaddrs 3 , 118.Xr uname 3 , 119system sensor readings. 120.Pp 121.It Xr pledge 2 122Can only reduce permissions; can only set a list of 123.Pa paths 124once. 125.El 126.Pp 127The 128.Ar promises 129is specified as a string, with space separated keywords: 130.Bl -tag -width "tmppath" -offset indent 131.It Va "stdio" 132The following system calls are permitted to allow most basic functions 133in libc, including memory allocation, most types of IO operations on 134previously allocated file descriptors: 135.Pp 136.Xr clock_getres 2 , 137.Xr clock_gettime 2 , 138.Xr close 2 , 139.Xr closefrom 2 , 140.Xr dup 2 , 141.Xr dup2 2 , 142.Xr dup3 2 , 143.Xr fchdir 2 , 144.Xr fcntl 2 , 145.Xr fstat 2 , 146.Xr fsync 2 , 147.Xr ftruncate 2 , 148.Xr getdents 2 , 149.Xr getdtablecount 2 , 150.Xr getegid 2 , 151.Xr getentropy 2 , 152.Xr geteuid 2 , 153.Xr getgid 2 , 154.Xr getgroups 2 , 155.Xr getitimer 2 , 156.Xr getlogin 2 , 157.Xr getpgid 2 , 158.Xr getpgrp 2 , 159.Xr getpid 2 , 160.Xr getppid 2 , 161.Xr getresgid 2 , 162.Xr getresuid 2 , 163.Xr getrlimit 2 , 164.Xr getsid 2 , 165.Xr getthrid 2 , 166.Xr gettimeofday 2 , 167.Xr getuid 2 , 168.Xr getuid 2 , 169.Xr issetugid 2 , 170.Xr kevent 2 , 171.Xr kqueue 2 , 172.Xr lseek 2 , 173.Xr madvise 2 , 174.Xr minherit 2 , 175.Xr mmap 2 , 176.Xr mprotect 2 , 177.Xr mquery 2 , 178.Xr munmap 2 , 179.Xr nanosleep 2 , 180.Xr pipe 2 , 181.Xr pipe2 2 , 182.Xr poll 2 , 183.Xr pread 2 , 184.Xr preadv 2 , 185.Xr pwrite 2 , 186.Xr pwritev 2 , 187.Xr read 2 , 188.Xr readv 2 , 189.Xr recvfrom 2 , 190.Xr recvmsg 2 , 191.Xr select 2 , 192.Xr sendmsg 2 , 193.Xr sendsyslog 2 , 194.Xr sendto 2 , 195.Xr setitimer 2 , 196.Xr shutdown 2 , 197.Xr sigaction 2 , 198.Xr sigprocmask 2 , 199.Xr sigreturn 2 , 200.Xr socketpair 2 , 201.Xr umask 2 , 202.Xr wait4 2 , 203.Xr write 2 , 204.Xr writev 2 . 205.Pp 206Note that 207.Xr sendto 2 208is only permitted if its destination socket address is 209.Dv NULL . 210As a result, all the expected functionalities of libc stdio work. 211.It Va "rpath" 212A number of system calls are allowed if they only cause 213read-only effects on the filesystem: 214.Pp 215.Xr chdir 2 , 216.Xr getcwd 3 , 217.Xr openat 2 , 218.Xr fstatat 2 , 219.Xr faccessat 2 , 220.Xr readlinkat 2 , 221.Xr lstat 2 , 222.Xr chmod 2 , 223.Xr fchmod 2 , 224.Xr fchmodat 2 , 225.Xr chflags 2 , 226.Xr chflagsat 2 , 227.Xr chown 2 , 228.Xr fchown 2 , 229.Xr fchownat 2 , 230.Xr fstat 2 , 231.Xr getfsstat 2 . 232.It Va "wpath" 233A number of system calls are allowed and may cause 234write-effects on the filesystem: 235.Pp 236.Xr getcwd 3 , 237.Xr openat 2 , 238.Xr fstatat 2 , 239.Xr faccessat 2 , 240.Xr readlinkat 2 , 241.Xr lstat 2 , 242.Xr chmod 2 , 243.Xr fchmod 2 , 244.Xr fchmodat 2 , 245.Xr chflags 2 , 246.Xr chflagsat 2 , 247.Xr chown 2 , 248.Xr fchown 2 , 249.Xr fchownat 2 , 250.Xr fstat 2 . 251.It Va "cpath" 252A number of system calls and sub-modes are allowed, which may 253create new files or directories in the filesystem: 254.Pp 255.Xr rename 2 , 256.Xr rmdir 2 , 257.Xr renameat 2 , 258.Xr link 2 , 259.Xr linkat 2 , 260.Xr symlink 2 , 261.Xr unlink 2 , 262.Xr unlinkat 2 , 263.Xr mkdir 2 , 264.Xr mkdirat 2 . 265.It Va "dpath" 266A number of system calls are allowed to create special files: 267.Pp 268.Xr mkfifo 2 , 269.Xr mknod 2 . 270.It Va "tmppath" 271A number of system calls are allowed to do operations in the 272.Pa /tmp 273directory, including create, read, or write: 274.Pp 275.Xr lstat 2 , 276.Xr chmod 2 , 277.Xr chflags 2 , 278.Xr chown 2 , 279.Xr unlink 2 , 280.Xr fstat 2 . 281.It Va "inet" 282The following system calls are allowed to operate in the 283.Dv AF_INET 284and 285.Dv AF_INET6 286domains: 287.Pp 288.Xr socket 2 , 289.Xr listen 2 , 290.Xr bind 2 , 291.Xr connect 2 , 292.Xr accept4 2 , 293.Xr accept 2 , 294.Xr getpeername 2 , 295.Xr getsockname 2 , 296.Xr setsockopt 2 , 297.Xr getsockopt 2 . 298.Pp 299.Xr setsockopt 2 300has been reduced in functionality substantially. 301.It Va "fattr" 302The following system calls are allowed to make explicit changes 303to fields in 304.Va struct stat 305relating to a file: 306.Pp 307.Xr utimes 2 , 308.Xr futimes 2 , 309.Xr utimensat 2 , 310.Xr futimens 2 , 311.Xr chmod 2 , 312.Xr fchmod 2 , 313.Xr fchmodat 2 , 314.Xr chflags 2 , 315.Xr chflagsat 2 , 316.Xr chown 2 , 317.Xr fchownat 2 , 318.Xr lchown 2 , 319.Xr fchown 2 , 320.Xr utimes 2 . 321.It Va "chown" 322The 323.Xr chown 2 324family is allowed to change the user or group on a file. 325.It Va "flock" 326File locking via 327.Xr fcntl 2 , 328.Xr flock 2 , 329.Xr lockf 3 , 330and 331.Xr open 2 332is allowed. 333No distinction is made between shared and exclusive locks. 334This promise is required for unlock as well as lock. 335.It Va "unix" 336The following system calls are allowed to operate in the 337.Dv AF_UNIX 338domain: 339.Pp 340.Xr socket 2 , 341.Xr listen 2 , 342.Xr bind 2 , 343.Xr connect 2 , 344.Xr accept4 2 , 345.Xr accept 2 , 346.Xr getpeername 2 , 347.Xr getsockname 2 , 348.Xr setsockopt 2 , 349.Xr getsockopt 2 . 350.It Va "dns" 351Subsequent to a successful 352.Xr open 2 353of 354.Pa /etc/resolv.conf , 355a few system calls become able to allow DNS network transactions: 356.Pp 357.Xr sendto 2 , 358.Xr recvfrom 2 , 359.Xr socket 2 , 360.Xr connect 2 . 361.It Va "getpw" 362This allows read-only opening of files in 363.Pa /etc 364for the 365.Xr getpwnam 3 , 366.Xr getgrnam 3 , 367.Xr getgrouplist 3 , 368and 369.Xr initgroups 3 370family of functions. 371They may also need to operate in a 372.Xr yp 8 373environment, so a successful 374.Xr open 2 375of 376.Pa /var/run/ypbind.lock 377enables 378.Va "inet" 379operations. 380.It Va "sendfd" 381Allows sending of file descriptors using 382.Xr sendmsg 2 . 383File descriptors referring to directories may not be passed. 384.It Va "recvfd" 385Allows receiving of file descriptors using 386.Xr recvmsg 2 . 387File descriptors referring to directories may not be passed. 388.It Va "ioctl" 389Allows a subset of 390.Xr ioctl 2 391operations: 392.Pp 393.Dv FIOCLEX , 394.Dv FIONCLEX , 395.Dv FIOASYNC , 396.Dv FIOGETOWN , 397and 398.Dv FIOSETOWN . 399On a tty device 400.Dv TIOCGETA will succeed otherwise fail with 401.Er EPERM . 402On a tty device, 403.Dv TIOCGPGRP 404and 405.Dv TIOCGWINSZ 406are allowed. 407A few other operations are allowed, but not listed here. 408.It Va "tty" 409In addition to allowing read-write operations on 410.Pa /dev/tty , 411this opens up a variety of 412.Xr ioctl 2 413requests used by tty devices. 414The following 415.Xr ioctl 2 416requests are permitted: 417.Dv TIOCSPGRP , 418.Dv TIOCGETA , 419.Dv TIOCGPGRP , 420.Dv TIOCGWINSZ , 421.Dv TIOCSWINSZ , 422.Dv TIOCSBRK , 423.Dv TIOCCDTR , 424.Dv TIOCSETA , 425.Dv TIOCSETAW 426and 427.Dv TIOCSETAF . 428.Pp 429If 430.Va "tty" 431is accompanied with 432.Va "rpath" , 433.Xr revoke 2 434is permitted. 435.It Va "proc" 436Allows the following process relationship operations: 437.Pp 438.Xr fork 2 , 439.Xr vfork 2 , 440.Xr kill 2 , 441.Xr getpriority 2 , 442.Xr setpriority 2 , 443.Xr setrlimit 2 , 444.Xr setpgid 2 , 445.Xr setsid 2 . 446.It Va "exec" 447Allows a process to call 448.Xr execve 2 . 449Coupled with the 450.Va "proc" 451promise, this allows a process to fork and execute another program. 452The new program starts running without pledge active and hopefully 453makes a new 454.Fn pledge . 455.It Va "prot_exec" 456Allows the use of 457.Dv PROT_EXEC 458with 459.Xr mmap 2 460and 461.Xr mprotect 2 . 462.It Va "settime" 463Allows the setting of system time, via the 464.Xr settimeofday 2 , 465.Xr adjtime 2 , 466and 467.Xr adjfreq 2 468system calls. 469.It Va "ps" 470Allows enough 471.Xr sysctl 3 472interfaces to allow inspection of processes operating on the system using 473programs like 474.Xr ps 1 . 475.It Va "vminfo" 476Allows enough 477.Xr sysctl 3 478interfaces to allow inspection of the system's virtual memory by 479programs like 480.Xr top 1 481and 482.Xr vmstat 8 . 483.It Va "id" 484Allows the following system calls which can change the rights of a 485process: 486.Pp 487.Xr setuid 2 , 488.Xr seteuid 2 , 489.Xr setreuid 2 , 490.Xr setresuid 2 , 491.Xr setgid 2 , 492.Xr setegid 2 , 493.Xr setregid 2 , 494.Xr setresgid 2 , 495.Xr setgroups 2 , 496.Xr setlogin 2 , 497.Xr setrlimit 2 , 498.Xr getpriority 2 , 499.Xr setpriority 2 . 500.It Va "pf" 501Allows a subset of 502.Xr ioctl 2 503operations on the 504.Xr pf 4 505device: 506.Pp 507.Dv DIOCADDRULE , 508.Dv DIOCGETSTATUS , 509.Dv DIOCNATLOOK , 510.Dv DIOCRADDTABLES , 511.Dv DIOCRCLRADDRS , 512.Dv DIOCRCLRTABLES , 513.Dv DIOCRCLRTSTATS , 514.Dv DIOCRGETTSTATS , 515.Dv DIOCRSETADDRS , 516.Dv DIOCXBEGIN , 517.Dv DIOCXCOMMIT . 518.It Va "audio" 519Allows a subset of 520.Xr ioctl 2 521operations on 522.Xr audio 4 523devices: 524.Pp 525.Dv AUDIO_GETPOS , 526.Dv AUDIO_GETPAR , 527.Dv AUDIO_SETPAR , 528.Dv AUDIO_START , 529.Dv AUDIO_STOP . 530.Pp 531See 532.Xr sio_open 3 533for more information on using the sndio API in combination with 534.Fn pledge . 535.El 536.Pp 537A whitelist of permitted paths may be provided in 538.Ar paths . 539All other paths will return 540.Er ENOENT . 541At least one promise is required to be pledged in order to activate a whitelist. 542.Sh RETURN VALUES 543.Rv -std 544.Sh ERRORS 545.Fn pledge 546will fail if: 547.Bl -tag -width Er 548.It Bq Er EFAULT 549.Fa paths 550or one of its elements, or 551.Fa promises 552points outside the process's allocated address space. 553.It Bq Er EINVAL 554.Ar request 555is malformed or contains invalid keywords. 556.It Bq Er ENAMETOOLONG 557An element of 558.Fa paths 559is too large, prepending 560.Fa cwd 561to it would exceed 562.Dv PATH_MAX 563bytes, or 564.Fa promises 565is too long. 566.It Bq Er EPERM 567This process is attempting to increase permissions. 568.It Bq Er E2BIG 569The 570.Ar paths 571array is too large, or the total number of bytes exceeds a 572system-imposed limit. 573The limit in the system as released is 262144 bytes 574.Pf ( Dv ARG_MAX ) . 575.El 576.Sh HISTORY 577The 578.Fn pledge 579system call first appeared in 580.Ox 5.9 . 581.Sh BUGS 582The path whitelist feature is not available at this time. 583