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