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