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