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