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