1.\" 2.\" Copyright (c) 2008-2010 Robert N. M. Watson 3.\" Copyright (c) 2012-2013 The FreeBSD Foundation 4.\" All rights reserved. 5.\" 6.\" This software was developed at the University of Cambridge Computer 7.\" Laboratory with support from a grant from Google, Inc. 8.\" 9.\" Portions of this documentation were written by Pawel Jakub Dawidek 10.\" under sponsorship from the FreeBSD Foundation. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd March 22, 2024 34.Dt RIGHTS 4 35.Os 36.Sh NAME 37.Nm Capability rights 38.Nd Capsicum capability rights for file descriptors 39.Sh DESCRIPTION 40When a file descriptor is created by a function such as 41.Xr accept 2 , 42.Xr accept4 2 , 43.Xr fhopen 2 , 44.Xr kqueue 2 , 45.Xr mq_open 2 , 46.Xr open 2 , 47.Xr openat 2 , 48.Xr pdfork 2 , 49.Xr pipe 2 , 50.Xr shm_open 2 , 51.Xr socket 2 52or 53.Xr socketpair 2 , 54it is assigned all capability rights. 55Those rights can be reduced (but never expanded) by using the 56.Xr cap_rights_limit 2 , 57.Xr cap_fcntls_limit 2 and 58.Xr cap_ioctls_limit 2 59system calls. 60Once capability rights are reduced, operations on the file descriptor will be 61limited to those permitted by rights. 62.Pp 63The complete list of capability rights is provided below. 64The 65.Vt cap_rights_t 66type is used to store list of capability rights. 67The 68.Xr cap_rights_init 3 69family of functions should be used to manage the structure. 70.Sh RIGHTS 71Note that rights are not simple bitmasks (and cannot be bitwise-ORed together). 72See 73.Xr cap_rights_init 3 74for details. 75.Pp 76The following rights are available: 77.Bl -tag -width CAP_RENAMEAT_SOURCE 78.It Dv CAP_ACCEPT 79Permit 80.Xr accept 2 81and 82.Xr accept4 2 . 83.It Dv CAP_ACL_CHECK 84Permit 85.Xr acl_valid_fd_np 3 . 86.It Dv CAP_ACL_DELETE 87Permit 88.Xr acl_delete_fd_np 3 . 89.It Dv CAP_ACL_GET 90Permit 91.Xr acl_get_fd 3 92and 93.Xr acl_get_fd_np 3 . 94.It Dv CAP_ACL_SET 95Permit 96.Xr acl_set_fd 3 97and 98.Xr acl_set_fd_np 3 . 99.It Dv CAP_BIND 100When not in capabilities mode, permit 101.Xr bind 2 102and 103.Xr bindat 2 104with special value 105.Dv AT_FDCWD 106in the 107.Fa fd 108parameter. 109Note that sockets can also become bound implicitly as a result of 110.Xr connect 2 111or 112.Xr send 2 , 113and that socket options set with 114.Xr setsockopt 2 115may also affect binding behavior. 116.It Dv CAP_BINDAT 117Permit 118.Xr bindat 2 . 119This right has to be present on the directory descriptor. 120This right includes the 121.Dv CAP_LOOKUP 122right. 123.It Dv CAP_CHFLAGSAT 124An alias to 125.Dv CAP_FCHFLAGS 126and 127.Dv CAP_LOOKUP . 128.It Dv CAP_CONNECT 129When not in capabilities mode, permit 130.Xr connect 2 131and 132.Xr connectat 2 133with special value 134.Dv AT_FDCWD 135in the 136.Fa fd 137parameter. 138This right is also required for 139.Xr sendto 2 140with a non-NULL destination address. 141.It Dv CAP_CONNECTAT 142Permit 143.Xr connectat 2 . 144This right has to be present on the directory descriptor. 145This right includes the 146.Dv CAP_LOOKUP 147right. 148.It Dv CAP_CREATE 149Permit 150.Xr openat 2 151with the 152.Dv O_CREAT 153flag. 154.It Dv CAP_EVENT 155Permit 156.Xr select 2 , 157.Xr poll 2 , 158and 159.Xr kevent 2 160to be used in monitoring the file descriptor for events. 161.It Dv CAP_EXTATTR_DELETE 162Permit 163.Xr extattr_delete_fd 2 . 164.It Dv CAP_EXTATTR_GET 165Permit 166.Xr extattr_get_fd 2 . 167.It Dv CAP_EXTATTR_LIST 168Permit 169.Xr extattr_list_fd 2 . 170.It Dv CAP_EXTATTR_SET 171Permit 172.Xr extattr_set_fd 2 . 173.It Dv CAP_FCHDIR 174Permit 175.Xr fchdir 2 . 176.It Dv CAP_FCHFLAGS 177Permit 178.Xr fchflags 2 179and 180.Xr chflagsat 2 181if the 182.Dv CAP_LOOKUP 183right is also present. 184.It Dv CAP_FCHMOD 185Permit 186.Xr fchmod 2 187and 188.Xr fchmodat 2 189if the 190.Dv CAP_LOOKUP 191right is also present. 192.It Dv CAP_FCHMODAT 193An alias to 194.Dv CAP_FCHMOD 195and 196.Dv CAP_LOOKUP . 197.It Dv CAP_FCHOWN 198Permit 199.Xr fchown 2 200and 201.Xr fchownat 2 202if the 203.Dv CAP_LOOKUP 204right is also present. 205.It Dv CAP_FCHOWNAT 206An alias to 207.Dv CAP_FCHOWN 208and 209.Dv CAP_LOOKUP . 210.It Dv CAP_FCNTL 211Permit 212.Xr fcntl 2 . 213Note that only the 214.Dv F_GETFL , 215.Dv F_SETFL , 216.Dv F_GETOWN 217and 218.Dv F_SETOWN 219commands require this capability right. 220Also note that the list of permitted commands can be further limited with the 221.Xr cap_fcntls_limit 2 222system call. 223.It Dv CAP_FEXECVE 224Permit 225.Xr fexecve 2 226and 227.Xr openat 2 228with the 229.Dv O_EXEC 230flag; 231.Dv CAP_READ 232is also required. 233.It Dv CAP_FLOCK 234Permit 235.Xr flock 2 , 236.Xr fcntl 2 237(with 238.Dv F_GETLK , 239.Dv F_SETLK , 240.Dv F_SETLKW 241or 242.Dv F_SETLK_REMOTE 243flag) and 244.Xr openat 2 245(with 246.Dv O_EXLOCK 247or 248.Dv O_SHLOCK 249flag). 250.It Dv CAP_FPATHCONF 251Permit 252.Xr fpathconf 2 . 253.It Dv CAP_FSCK 254Permit UFS background-fsck operations on the descriptor. 255.It Dv CAP_FSTAT 256Permit 257.Xr fstat 2 258and 259.Xr fstatat 2 260if the 261.Dv CAP_LOOKUP 262right is also present. 263.It Dv CAP_FSTATAT 264An alias to 265.Dv CAP_FSTAT 266and 267.Dv CAP_LOOKUP . 268.It Dv CAP_FSTATFS 269Permit 270.Xr fstatfs 2 . 271.It Dv CAP_FSYNC 272Permit 273.Xr aio_fsync 2 , 274.Xr fdatasync 2 , 275.Xr fsync 2 276and 277.Xr openat 2 278with 279.Dv O_FSYNC 280or 281.Dv O_SYNC 282flag. 283.It Dv CAP_FTRUNCATE 284Permit 285.Xr ftruncate 2 286and 287.Xr openat 2 288with the 289.Dv O_TRUNC 290flag. 291.It Dv CAP_FUTIMES 292Permit 293.Xr futimens 2 294and 295.Xr futimes 2 , 296and permit 297.Xr futimesat 2 298and 299.Xr utimensat 2 300if the 301.Dv CAP_LOOKUP 302right is also present. 303.It Dv CAP_FUTIMESAT 304An alias to 305.Dv CAP_FUTIMES 306and 307.Dv CAP_LOOKUP . 308.It Dv CAP_GETPEERNAME 309Permit 310.Xr getpeername 2 . 311.It Dv CAP_GETSOCKNAME 312Permit 313.Xr getsockname 2 . 314.It Dv CAP_GETSOCKOPT 315Permit 316.Xr getsockopt 2 . 317.It Dv CAP_IOCTL 318Permit 319.Xr ioctl 2 . 320Be aware that this system call has enormous scope, including potentially 321global scope for some objects. 322The list of permitted ioctl commands can be further limited with the 323.Xr cap_ioctls_limit 2 324system call. 325.It Dv CAP_KQUEUE 326An alias to 327.Dv CAP_KQUEUE_CHANGE 328and 329.Dv CAP_KQUEUE_EVENT . 330.It Dv CAP_KQUEUE_CHANGE 331Permit 332.Xr kevent 2 333on a 334.Xr kqueue 2 335descriptor that modifies list of monitored events (the 336.Fa changelist 337argument is non-NULL). 338.It Dv CAP_KQUEUE_EVENT 339Permit 340.Xr kevent 2 341on a 342.Xr kqueue 2 343descriptor that monitors events (the 344.Fa eventlist 345argument is non-NULL). 346.Dv CAP_EVENT 347is also required on file descriptors that will be monitored using 348.Xr kevent 2 . 349.It Dv CAP_LINKAT_SOURCE 350Permit 351.Xr linkat 2 352on the source directory descriptor. 353This right includes the 354.Dv CAP_LOOKUP 355right. 356.Pp 357Warning: 358.Dv CAP_LINKAT_SOURCE 359makes it possible to link files in a directory for which file 360descriptors exist that have additional rights. 361For example, 362a file stored in a directory that does not allow 363.Dv CAP_READ 364may be linked in another directory that does allow 365.Dv CAP_READ , 366thereby granting read access to a file that is otherwise unreadable. 367.It Dv CAP_LINKAT_TARGET 368Permit 369.Xr linkat 2 370on the target directory descriptor. 371This right includes the 372.Dv CAP_LOOKUP 373right. 374.It Dv CAP_LISTEN 375Permit 376.Xr listen 2 ; 377not much use (generally) without 378.Dv CAP_BIND . 379.It Dv CAP_LOOKUP 380Permit the file descriptor to be used as a starting directory for calls such as 381.Xr linkat 2 , 382.Xr openat 2 , 383and 384.Xr unlinkat 2 . 385.It Dv CAP_MAC_GET 386Permit 387.Xr mac_get_fd 3 . 388.It Dv CAP_MAC_SET 389Permit 390.Xr mac_set_fd 3 . 391.It Dv CAP_MKDIRAT 392Permit 393.Xr mkdirat 2 . 394This right includes the 395.Dv CAP_LOOKUP 396right. 397.It Dv CAP_MKFIFOAT 398Permit 399.Xr mkfifoat 2 . 400This right includes the 401.Dv CAP_LOOKUP 402right. 403.It Dv CAP_MKNODAT 404Permit 405.Xr mknodat 2 . 406This right includes the 407.Dv CAP_LOOKUP 408right. 409.It Dv CAP_MMAP 410Permit 411.Xr mmap 2 412with the 413.Dv PROT_NONE 414protection. 415.It Dv CAP_MMAP_R 416Permit 417.Xr mmap 2 418with the 419.Dv PROT_READ 420protection. 421This right includes the 422.Dv CAP_READ 423and 424.Dv CAP_SEEK 425rights. 426.It Dv CAP_MMAP_RW 427An alias to 428.Dv CAP_MMAP_R 429and 430.Dv CAP_MMAP_W . 431.It Dv CAP_MMAP_RWX 432An alias to 433.Dv CAP_MMAP_R , 434.Dv CAP_MMAP_W 435and 436.Dv CAP_MMAP_X . 437.It Dv CAP_MMAP_RX 438An alias to 439.Dv CAP_MMAP_R 440and 441.Dv CAP_MMAP_X . 442.It Dv CAP_MMAP_W 443Permit 444.Xr mmap 2 445with the 446.Dv PROT_WRITE 447protection. 448This right includes the 449.Dv CAP_WRITE 450and 451.Dv CAP_SEEK 452rights. 453.It Dv CAP_MMAP_WX 454An alias to 455.Dv CAP_MMAP_W 456and 457.Dv CAP_MMAP_X . 458.It Dv CAP_MMAP_X 459Permit 460.Xr mmap 2 461with the 462.Dv PROT_EXEC 463protection. 464This right includes the 465.Dv CAP_SEEK 466right. 467.It Dv CAP_PDGETPID 468Permit 469.Xr pdgetpid 2 . 470.It Dv CAP_PDKILL 471Permit 472.Xr pdkill 2 . 473.It Dv CAP_PEELOFF 474Permit 475.Xr sctp_peeloff 2 . 476.It Dv CAP_PREAD 477An alias to 478.Dv CAP_READ 479and 480.Dv CAP_SEEK . 481.It Dv CAP_PWRITE 482An alias to 483.Dv CAP_SEEK 484and 485.Dv CAP_WRITE . 486.It Dv CAP_READ 487Permit 488.Xr aio_read 2 489.Dv ( CAP_SEEK 490is also required), 491.Xr openat 2 492with the 493.Dv O_RDONLY flag, 494.Xr read 2 , 495.Xr readv 2 , 496.Xr recv 2 , 497.Xr recvfrom 2 , 498.Xr recvmsg 2 , 499.Xr pread 2 500.Dv ( CAP_SEEK 501is also required), 502.Xr preadv 2 503.Dv ( CAP_SEEK 504is also required) and related system calls. 505.It Dv CAP_RECV 506An alias to 507.Dv CAP_READ . 508.It Dv CAP_RENAMEAT_SOURCE 509Permit 510.Xr renameat 2 511on the source directory descriptor. 512This right includes the 513.Dv CAP_LOOKUP 514right. 515.Pp 516Warning: 517.Dv CAP_RENAMEAT_SOURCE 518makes it possible to move files to a directory for which file 519descriptors exist that have additional rights. 520For example, 521a file stored in a directory that does not allow 522.Dv CAP_READ 523may be moved to another directory that does allow 524.Dv CAP_READ , 525thereby granting read access to a file that is otherwise unreadable. 526.It Dv CAP_RENAMEAT_TARGET 527Permit 528.Xr renameat 2 529on the target directory descriptor. 530This right includes the 531.Dv CAP_LOOKUP 532right. 533.It Dv CAP_SEEK 534Permit operations that seek on the file descriptor, such as 535.Xr lseek 2 , 536but also required for I/O system calls that can read or write at any position 537in the file, such as 538.Xr pread 2 539and 540.Xr pwrite 2 . 541.It Dv CAP_SEM_GETVALUE 542Permit 543.Xr sem_getvalue 3 . 544.It Dv CAP_SEM_POST 545Permit 546.Xr sem_post 3 . 547.It Dv CAP_SEM_WAIT 548Permit 549.Xr sem_wait 3 550and 551.Xr sem_trywait 3 . 552.It Dv CAP_SEND 553An alias to 554.Dv CAP_WRITE . 555.It Dv CAP_SETSOCKOPT 556Permit 557.Xr setsockopt 2 ; 558this controls various aspects of socket behavior and may affect binding, 559connecting, and other behaviors with global scope. 560.It Dv CAP_SHUTDOWN 561Permit explicit 562.Xr shutdown 2 ; 563closing the socket will also generally shut down any connections on it. 564.It Dv CAP_SYMLINKAT 565Permit 566.Xr symlinkat 2 . 567This right includes the 568.Dv CAP_LOOKUP 569right. 570.It Dv CAP_TTYHOOK 571Allow configuration of TTY hooks, such as 572.Xr snp 4 , 573on the file descriptor. 574.It Dv CAP_UNLINKAT 575Permit 576.Xr unlinkat 2 577and 578.Xr renameat 2 . 579This right is only required for 580.Xr renameat 2 581on the destination directory descriptor if the destination object already 582exists and will be removed by the rename. 583This right includes the 584.Dv CAP_LOOKUP 585right. 586.It Dv CAP_WRITE 587Allow 588.Xr aio_write 2 , 589.Xr openat 2 590with 591.Dv O_WRONLY 592and 593.Dv O_APPEND 594flags set, 595.Xr send 2 , 596.Xr sendmsg 2 , 597.Xr sendto 2 , 598.Xr write 2 , 599.Xr writev 2 , 600.Xr pwrite 2 , 601.Xr pwritev 2 602and related system calls. 603For 604.Xr sendto 2 605with a non-NULL connection address, 606.Dv CAP_CONNECT 607is also required. 608For 609.Xr openat 2 610with the 611.Dv O_WRONLY 612flag, but without the 613.Dv O_APPEND 614flag, 615.Dv CAP_SEEK 616is also required. 617For 618.Xr aio_write 2 , 619.Xr pwrite 2 620and 621.Xr pwritev 2 622.Dv CAP_SEEK 623is also required. 624.El 625.Sh SEE ALSO 626.Xr accept 2 , 627.Xr accept4 2 , 628.Xr aio_fsync 2 , 629.Xr aio_read 2 , 630.Xr aio_write 2 , 631.Xr bind 2 , 632.Xr bindat 2 , 633.Xr cap_enter 2 , 634.Xr cap_fcntls_limit 2 , 635.Xr cap_ioctls_limit 2 , 636.Xr cap_rights_limit 2 , 637.Xr chflagsat 2 , 638.Xr connect 2 , 639.Xr connectat 2 , 640.Xr extattr_delete_fd 2 , 641.Xr extattr_get_fd 2 , 642.Xr extattr_list_fd 2 , 643.Xr extattr_set_fd 2 , 644.Xr fchflags 2 , 645.Xr fchmod 2 , 646.Xr fchmodat 2 , 647.Xr fchown 2 , 648.Xr fchownat 2 , 649.Xr fcntl 2 , 650.Xr fexecve 2 , 651.Xr fhopen 2 , 652.Xr flock 2 , 653.Xr fpathconf 2 , 654.Xr fstat 2 , 655.Xr fstatat 2 , 656.Xr fstatfs 2 , 657.Xr fsync 2 , 658.Xr ftruncate 2 , 659.Xr futimes 2 , 660.Xr getpeername 2 , 661.Xr getsockname 2 , 662.Xr getsockopt 2 , 663.Xr ioctl 2 , 664.Xr kevent 2 , 665.Xr kqueue 2 , 666.Xr linkat 2 , 667.Xr listen 2 , 668.Xr mmap 2 , 669.Xr mq_open 2 , 670.Xr open 2 , 671.Xr openat 2 , 672.Xr pdfork 2 , 673.Xr pdgetpid 2 , 674.Xr pdkill 2 , 675.Xr pdwait4 2 , 676.Xr pipe 2 , 677.Xr poll 2 , 678.Xr pread 2 , 679.Xr preadv 2 , 680.Xr pwrite 2 , 681.Xr pwritev 2 , 682.Xr read 2 , 683.Xr readv 2 , 684.Xr recv 2 , 685.Xr recvfrom 2 , 686.Xr recvmsg 2 , 687.Xr renameat 2 , 688.Xr sctp_peeloff 2 , 689.Xr select 2 , 690.Xr send 2 , 691.Xr sendmsg 2 , 692.Xr sendto 2 , 693.Xr setsockopt 2 , 694.Xr shm_open 2 , 695.Xr shutdown 2 , 696.Xr socket 2 , 697.Xr socketpair 2 , 698.Xr symlinkat 2 , 699.Xr unlinkat 2 , 700.Xr write 2 , 701.Xr writev 2 , 702.Xr acl_delete_fd_np 3 , 703.Xr acl_get_fd 3 , 704.Xr acl_get_fd_np 3 , 705.Xr acl_set_fd 3 , 706.Xr acl_set_fd_np 3 , 707.Xr acl_valid_fd_np 3 , 708.Xr mac_get_fd 3 , 709.Xr mac_set_fd 3 , 710.Xr sem_getvalue 3 , 711.Xr sem_post 3 , 712.Xr sem_trywait 3 , 713.Xr sem_wait 3 , 714.Xr capsicum 4 , 715.Xr snp 4 716.Sh HISTORY 717Support for capabilities and capabilities mode was developed as part of the 718.Tn TrustedBSD 719Project. 720.Sh AUTHORS 721.An -nosplit 722This manual page was created by 723.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 724under sponsorship from the FreeBSD Foundation based on the 725.Xr cap_new 2 726manual page by 727.An Robert Watson Aq Mt rwatson@FreeBSD.org . 728