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 May 22, 2025 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_FCHROOT 213Permit 214.Xr fchroot 2 . 215.It Dv CAP_FCNTL 216Permit 217.Xr fcntl 2 . 218Note that only the 219.Dv F_GETFL , 220.Dv F_SETFL , 221.Dv F_GETOWN 222and 223.Dv F_SETOWN 224commands require this capability right. 225Also note that the list of permitted commands can be further limited with the 226.Xr cap_fcntls_limit 2 227system call. 228.It Dv CAP_FEXECVE 229Permit 230.Xr fexecve 2 231and 232.Xr openat 2 233with the 234.Dv O_EXEC 235flag; 236.Dv CAP_READ 237is also required. 238.It Dv CAP_FLOCK 239Permit 240.Xr flock 2 , 241.Xr fcntl 2 242(with 243.Dv F_GETLK , 244.Dv F_SETLK , 245.Dv F_SETLKW 246or 247.Dv F_SETLK_REMOTE 248flag) and 249.Xr openat 2 250(with 251.Dv O_EXLOCK 252or 253.Dv O_SHLOCK 254flag). 255.It Dv CAP_FPATHCONF 256Permit 257.Xr fpathconf 2 . 258.It Dv CAP_FSCK 259Permit UFS background-fsck operations on the descriptor. 260.It Dv CAP_FSTAT 261Permit 262.Xr fstat 2 263and 264.Xr fstatat 2 265if the 266.Dv CAP_LOOKUP 267right is also present. 268.It Dv CAP_FSTATAT 269An alias to 270.Dv CAP_FSTAT 271and 272.Dv CAP_LOOKUP . 273.It Dv CAP_FSTATFS 274Permit 275.Xr fstatfs 2 . 276.It Dv CAP_FSYNC 277Permit 278.Xr aio_fsync 2 , 279.Xr fdatasync 2 , 280.Xr fsync 2 281and 282.Xr openat 2 283with 284.Dv O_DSYNC , 285.Dv O_FSYNC , 286or 287.Dv O_SYNC 288flag. 289.It Dv CAP_FTRUNCATE 290Permit 291.Xr ftruncate 2 292and 293.Xr openat 2 294with the 295.Dv O_TRUNC 296flag. 297.It Dv CAP_FUTIMES 298Permit 299.Xr futimens 2 300and 301.Xr futimes 2 , 302and permit 303.Xr futimesat 2 304and 305.Xr utimensat 2 306if the 307.Dv CAP_LOOKUP 308right is also present. 309.It Dv CAP_FUTIMESAT 310An alias to 311.Dv CAP_FUTIMES 312and 313.Dv CAP_LOOKUP . 314.It Dv CAP_GETPEERNAME 315Permit 316.Xr getpeername 2 . 317.It Dv CAP_GETSOCKNAME 318Permit 319.Xr getsockname 2 . 320.It Dv CAP_GETSOCKOPT 321Permit 322.Xr getsockopt 2 . 323.It Dv CAP_INOTIFY_ADD 324Permit 325.Xr inotify_add_watch 2 326and 327.Xr inotify_add_watch_at 2 . 328.It Dv CAP_INOTIFY_RM 329Permit 330.Xr inotify_rm_watch 2 . 331.It Dv CAP_IOCTL 332Permit 333.Xr ioctl 2 . 334Be aware that this system call has enormous scope, including potentially 335global scope for some objects. 336The list of permitted ioctl commands can be further limited with the 337.Xr cap_ioctls_limit 2 338system call. 339.It Dv CAP_KQUEUE 340An alias to 341.Dv CAP_KQUEUE_CHANGE 342and 343.Dv CAP_KQUEUE_EVENT . 344.It Dv CAP_KQUEUE_CHANGE 345Permit 346.Xr kevent 2 347on a 348.Xr kqueue 2 349descriptor that modifies list of monitored events (the 350.Fa changelist 351argument is non-NULL). 352.It Dv CAP_KQUEUE_EVENT 353Permit 354.Xr kevent 2 355on a 356.Xr kqueue 2 357descriptor that monitors events (the 358.Fa eventlist 359argument is non-NULL). 360.Dv CAP_EVENT 361is also required on file descriptors that will be monitored using 362.Xr kevent 2 . 363.It Dv CAP_LINKAT_SOURCE 364Permit 365.Xr linkat 2 366on the source directory descriptor. 367This right includes the 368.Dv CAP_LOOKUP 369right. 370.Pp 371Warning: 372.Dv CAP_LINKAT_SOURCE 373makes it possible to link files in a directory for which file 374descriptors exist that have additional rights. 375For example, 376a file stored in a directory that does not allow 377.Dv CAP_READ 378may be linked in another directory that does allow 379.Dv CAP_READ , 380thereby granting read access to a file that is otherwise unreadable. 381.It Dv CAP_LINKAT_TARGET 382Permit 383.Xr linkat 2 384on the target directory descriptor. 385This right includes the 386.Dv CAP_LOOKUP 387right. 388.It Dv CAP_LISTEN 389Permit 390.Xr listen 2 ; 391not much use (generally) without 392.Dv CAP_BIND . 393.It Dv CAP_LOOKUP 394Permit the file descriptor to be used as a starting directory for calls such as 395.Xr linkat 2 , 396.Xr openat 2 , 397and 398.Xr unlinkat 2 . 399.It Dv CAP_MAC_GET 400Permit 401.Xr mac_get_fd 3 . 402.It Dv CAP_MAC_SET 403Permit 404.Xr mac_set_fd 3 . 405.It Dv CAP_MKDIRAT 406Permit 407.Xr mkdirat 2 . 408This right includes the 409.Dv CAP_LOOKUP 410right. 411.It Dv CAP_MKFIFOAT 412Permit 413.Xr mkfifoat 2 . 414This right includes the 415.Dv CAP_LOOKUP 416right. 417.It Dv CAP_MKNODAT 418Permit 419.Xr mknodat 2 . 420This right includes the 421.Dv CAP_LOOKUP 422right. 423.It Dv CAP_MMAP 424Permit 425.Xr mmap 2 426with the 427.Dv PROT_NONE 428protection. 429.It Dv CAP_MMAP_R 430Permit 431.Xr mmap 2 432with the 433.Dv PROT_READ 434protection. 435This right includes the 436.Dv CAP_READ 437and 438.Dv CAP_SEEK 439rights. 440.It Dv CAP_MMAP_RW 441An alias to 442.Dv CAP_MMAP_R 443and 444.Dv CAP_MMAP_W . 445.It Dv CAP_MMAP_RWX 446An alias to 447.Dv CAP_MMAP_R , 448.Dv CAP_MMAP_W 449and 450.Dv CAP_MMAP_X . 451.It Dv CAP_MMAP_RX 452An alias to 453.Dv CAP_MMAP_R 454and 455.Dv CAP_MMAP_X . 456.It Dv CAP_MMAP_W 457Permit 458.Xr mmap 2 459with the 460.Dv PROT_WRITE 461protection. 462This right includes the 463.Dv CAP_WRITE 464and 465.Dv CAP_SEEK 466rights. 467.It Dv CAP_MMAP_WX 468An alias to 469.Dv CAP_MMAP_W 470and 471.Dv CAP_MMAP_X . 472.It Dv CAP_MMAP_X 473Permit 474.Xr mmap 2 475with the 476.Dv PROT_EXEC 477protection. 478This right includes the 479.Dv CAP_SEEK 480right. 481.It Dv CAP_PDGETPID 482Permit 483.Xr pdgetpid 2 . 484.It Dv CAP_PDKILL 485Permit 486.Xr pdkill 2 . 487.It Dv CAP_PEELOFF 488Permit 489.Xr sctp_peeloff 2 . 490.It Dv CAP_PREAD 491An alias to 492.Dv CAP_READ 493and 494.Dv CAP_SEEK . 495.It Dv CAP_PWRITE 496An alias to 497.Dv CAP_SEEK 498and 499.Dv CAP_WRITE . 500.It Dv CAP_READ 501Permit 502.Xr aio_read 2 503.Dv ( CAP_SEEK 504is also required), 505.Xr openat 2 506with the 507.Dv O_RDONLY flag, 508.Xr read 2 , 509.Xr readv 2 , 510.Xr recv 2 , 511.Xr recvfrom 2 , 512.Xr recvmsg 2 , 513.Xr pread 2 514.Dv ( CAP_SEEK 515is also required), 516.Xr preadv 2 517.Dv ( CAP_SEEK 518is also required), 519.Xr getdents 2 , 520.Xr getdirentries 2 , 521and related system calls. 522.It Dv CAP_RECV 523An alias to 524.Dv CAP_READ . 525.It Dv CAP_RENAMEAT_SOURCE 526Permit 527.Xr renameat 2 528on the source directory descriptor. 529This right includes the 530.Dv CAP_LOOKUP 531right. 532.Pp 533Warning: 534.Dv CAP_RENAMEAT_SOURCE 535makes it possible to move files to a directory for which file 536descriptors exist that have additional rights. 537For example, 538a file stored in a directory that does not allow 539.Dv CAP_READ 540may be moved to another directory that does allow 541.Dv CAP_READ , 542thereby granting read access to a file that is otherwise unreadable. 543.It Dv CAP_RENAMEAT_TARGET 544Permit 545.Xr renameat 2 546on the target directory descriptor. 547This right includes the 548.Dv CAP_LOOKUP 549right. 550.It Dv CAP_SEEK 551Permit operations that seek on the file descriptor, such as 552.Xr lseek 2 , 553but also required for I/O system calls that can read or write at any position 554in the file, such as 555.Xr pread 2 556and 557.Xr pwrite 2 . 558.It Dv CAP_SEM_GETVALUE 559Permit 560.Xr sem_getvalue 3 . 561.It Dv CAP_SEM_POST 562Permit 563.Xr sem_post 3 . 564.It Dv CAP_SEM_WAIT 565Permit 566.Xr sem_wait 3 567and 568.Xr sem_trywait 3 . 569.It Dv CAP_SEND 570An alias to 571.Dv CAP_WRITE . 572.It Dv CAP_SETSOCKOPT 573Permit 574.Xr setsockopt 2 ; 575this controls various aspects of socket behavior and may affect binding, 576connecting, and other behaviors with global scope. 577.It Dv CAP_SHUTDOWN 578Permit explicit 579.Xr shutdown 2 ; 580closing the socket will also generally shut down any connections on it. 581.It Dv CAP_SYMLINKAT 582Permit 583.Xr symlinkat 2 . 584This right includes the 585.Dv CAP_LOOKUP 586right. 587.It Dv CAP_TTYHOOK 588Allow configuration of TTY hooks, such as 589.Xr snp 4 , 590on the file descriptor. 591.It Dv CAP_UNLINKAT 592Permit 593.Xr unlinkat 2 594and 595.Xr renameat 2 . 596This right is only required for 597.Xr renameat 2 598on the destination directory descriptor if the destination object already 599exists and will be removed by the rename. 600This right includes the 601.Dv CAP_LOOKUP 602right. 603.It Dv CAP_WRITE 604Allow 605.Xr aio_write 2 , 606.Xr openat 2 607with 608.Dv O_WRONLY 609and 610.Dv O_APPEND 611flags set, 612.Xr send 2 , 613.Xr sendmsg 2 , 614.Xr sendto 2 , 615.Xr write 2 , 616.Xr writev 2 , 617.Xr pwrite 2 , 618.Xr pwritev 2 619and related system calls. 620For 621.Xr sendto 2 622with a non-NULL connection address, 623.Dv CAP_CONNECT 624is also required. 625For 626.Xr openat 2 627with the 628.Dv O_WRONLY 629flag, but without the 630.Dv O_APPEND 631or 632.Dv O_TRUNC 633flag, 634.Dv CAP_SEEK 635is also required. 636For 637.Xr aio_write 2 , 638.Xr pwrite 2 639and 640.Xr pwritev 2 641.Dv CAP_SEEK 642is also required. 643.El 644.Sh SEE ALSO 645.Xr accept 2 , 646.Xr accept4 2 , 647.Xr aio_fsync 2 , 648.Xr aio_read 2 , 649.Xr aio_write 2 , 650.Xr bind 2 , 651.Xr bindat 2 , 652.Xr cap_enter 2 , 653.Xr cap_fcntls_limit 2 , 654.Xr cap_ioctls_limit 2 , 655.Xr cap_rights_limit 2 , 656.Xr chflagsat 2 , 657.Xr connect 2 , 658.Xr connectat 2 , 659.Xr extattr_delete_fd 2 , 660.Xr extattr_get_fd 2 , 661.Xr extattr_list_fd 2 , 662.Xr extattr_set_fd 2 , 663.Xr fchflags 2 , 664.Xr fchmod 2 , 665.Xr fchmodat 2 , 666.Xr fchown 2 , 667.Xr fchownat 2 , 668.Xr fcntl 2 , 669.Xr fexecve 2 , 670.Xr fhopen 2 , 671.Xr flock 2 , 672.Xr fpathconf 2 , 673.Xr fstat 2 , 674.Xr fstatat 2 , 675.Xr fstatfs 2 , 676.Xr fsync 2 , 677.Xr ftruncate 2 , 678.Xr futimes 2 , 679.Xr getdents 2 , 680.Xr getdirentries 2 , 681.Xr getpeername 2 , 682.Xr getsockname 2 , 683.Xr getsockopt 2 , 684.Xr ioctl 2 , 685.Xr kevent 2 , 686.Xr kqueue 2 , 687.Xr linkat 2 , 688.Xr listen 2 , 689.Xr mmap 2 , 690.Xr mq_open 2 , 691.Xr open 2 , 692.Xr openat 2 , 693.Xr pdfork 2 , 694.Xr pdgetpid 2 , 695.Xr pdkill 2 , 696.Xr pdwait4 2 , 697.Xr pipe 2 , 698.Xr poll 2 , 699.Xr pread 2 , 700.Xr preadv 2 , 701.Xr pwrite 2 , 702.Xr pwritev 2 , 703.Xr read 2 , 704.Xr readv 2 , 705.Xr recv 2 , 706.Xr recvfrom 2 , 707.Xr recvmsg 2 , 708.Xr renameat 2 , 709.Xr sctp_peeloff 2 , 710.Xr select 2 , 711.Xr send 2 , 712.Xr sendmsg 2 , 713.Xr sendto 2 , 714.Xr setsockopt 2 , 715.Xr shm_open 2 , 716.Xr shutdown 2 , 717.Xr socket 2 , 718.Xr socketpair 2 , 719.Xr symlinkat 2 , 720.Xr unlinkat 2 , 721.Xr write 2 , 722.Xr writev 2 , 723.Xr acl_delete_fd_np 3 , 724.Xr acl_get_fd 3 , 725.Xr acl_get_fd_np 3 , 726.Xr acl_set_fd 3 , 727.Xr acl_set_fd_np 3 , 728.Xr acl_valid_fd_np 3 , 729.Xr mac_get_fd 3 , 730.Xr mac_set_fd 3 , 731.Xr sem_getvalue 3 , 732.Xr sem_post 3 , 733.Xr sem_trywait 3 , 734.Xr sem_wait 3 , 735.Xr capsicum 4 , 736.Xr snp 4 737.Sh HISTORY 738Support for capabilities and capabilities mode was developed as part of the 739.Tn TrustedBSD 740Project. 741.Sh AUTHORS 742.An -nosplit 743This manual page was created by 744.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 745under sponsorship from the FreeBSD Foundation based on the 746.Xr cap_new 2 747manual page by 748.An Robert Watson Aq Mt rwatson@FreeBSD.org . 749