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 February 28, 2019 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_PEELOFF 471Permit 472.Xr sctp_peeloff 2 . 473.It Dv CAP_PREAD 474An alias to 475.Dv CAP_READ 476and 477.Dv CAP_SEEK . 478.It Dv CAP_PWRITE 479An alias to 480.Dv CAP_SEEK 481and 482.Dv CAP_WRITE . 483.It Dv CAP_READ 484Permit 485.Xr aio_read 2 486.Dv ( CAP_SEEK 487is also required), 488.Xr openat 2 489with the 490.Dv O_RDONLY flag, 491.Xr read 2 , 492.Xr readv 2 , 493.Xr recv 2 , 494.Xr recvfrom 2 , 495.Xr recvmsg 2 , 496.Xr pread 2 497.Dv ( CAP_SEEK 498is also required), 499.Xr preadv 2 500.Dv ( CAP_SEEK 501is also required) and related system calls. 502.It Dv CAP_RECV 503An alias to 504.Dv CAP_READ . 505.It Dv CAP_RENAMEAT_SOURCE 506Permit 507.Xr renameat 2 508on the source directory descriptor. 509This right includes the 510.Dv CAP_LOOKUP 511right. 512.Pp 513Warning: 514.Dv CAP_RENAMEAT_SOURCE 515makes it possible to move files to a directory for which file 516descriptors exist that have additional rights. 517For example, 518a file stored in a directory that does not allow 519.Dv CAP_READ 520may be moved to another directory that does allow 521.Dv CAP_READ , 522thereby granting read access to a file that is otherwise unreadable. 523.It Dv CAP_RENAMEAT_TARGET 524Permit 525.Xr renameat 2 526on the target directory descriptor. 527This right includes the 528.Dv CAP_LOOKUP 529right. 530.It Dv CAP_SEEK 531Permit operations that seek on the file descriptor, such as 532.Xr lseek 2 , 533but also required for I/O system calls that can read or write at any position 534in the file, such as 535.Xr pread 2 536and 537.Xr pwrite 2 . 538.It Dv CAP_SEM_GETVALUE 539Permit 540.Xr sem_getvalue 3 . 541.It Dv CAP_SEM_POST 542Permit 543.Xr sem_post 3 . 544.It Dv CAP_SEM_WAIT 545Permit 546.Xr sem_wait 3 547and 548.Xr sem_trywait 3 . 549.It Dv CAP_SEND 550An alias to 551.Dv CAP_WRITE . 552.It Dv CAP_SETSOCKOPT 553Permit 554.Xr setsockopt 2 ; 555this controls various aspects of socket behavior and may affect binding, 556connecting, and other behaviors with global scope. 557.It Dv CAP_SHUTDOWN 558Permit explicit 559.Xr shutdown 2 ; 560closing the socket will also generally shut down any connections on it. 561.It Dv CAP_SYMLINKAT 562Permit 563.Xr symlinkat 2 . 564This right includes the 565.Dv CAP_LOOKUP 566right. 567.It Dv CAP_TTYHOOK 568Allow configuration of TTY hooks, such as 569.Xr snp 4 , 570on the file descriptor. 571.It Dv CAP_UNLINKAT 572Permit 573.Xr unlinkat 2 574and 575.Xr renameat 2 . 576This right is only required for 577.Xr renameat 2 578on the destination directory descriptor if the destination object already 579exists and will be removed by the rename. 580This right includes the 581.Dv CAP_LOOKUP 582right. 583.It Dv CAP_WRITE 584Allow 585.Xr aio_write 2 , 586.Xr openat 2 587with 588.Dv O_WRONLY 589and 590.Dv O_APPEND 591flags set, 592.Xr send 2 , 593.Xr sendmsg 2 , 594.Xr sendto 2 , 595.Xr write 2 , 596.Xr writev 2 , 597.Xr pwrite 2 , 598.Xr pwritev 2 599and related system calls. 600For 601.Xr sendto 2 602with a non-NULL connection address, 603.Dv CAP_CONNECT 604is also required. 605For 606.Xr openat 2 607with the 608.Dv O_WRONLY 609flag, but without the 610.Dv O_APPEND 611flag, 612.Dv CAP_SEEK 613is also required. 614For 615.Xr aio_write 2 , 616.Xr pwrite 2 617and 618.Xr pwritev 2 619.Dv CAP_SEEK 620is also required. 621.El 622.Sh SEE ALSO 623.Xr accept 2 , 624.Xr accept4 2 , 625.Xr aio_fsync 2 , 626.Xr aio_read 2 , 627.Xr aio_write 2 , 628.Xr bind 2 , 629.Xr bindat 2 , 630.Xr cap_enter 2 , 631.Xr cap_fcntls_limit 2 , 632.Xr cap_ioctls_limit 2 , 633.Xr cap_rights_limit 2 , 634.Xr chflagsat 2 , 635.Xr connect 2 , 636.Xr connectat 2 , 637.Xr extattr_delete_fd 2 , 638.Xr extattr_get_fd 2 , 639.Xr extattr_list_fd 2 , 640.Xr extattr_set_fd 2 , 641.Xr fchflags 2 , 642.Xr fchmod 2 , 643.Xr fchmodat 2 , 644.Xr fchown 2 , 645.Xr fchownat 2 , 646.Xr fcntl 2 , 647.Xr fexecve 2 , 648.Xr fhopen 2 , 649.Xr flock 2 , 650.Xr fpathconf 2 , 651.Xr fstat 2 , 652.Xr fstatat 2 , 653.Xr fstatfs 2 , 654.Xr fsync 2 , 655.Xr ftruncate 2 , 656.Xr futimes 2 , 657.Xr getpeername 2 , 658.Xr getsockname 2 , 659.Xr getsockopt 2 , 660.Xr ioctl 2 , 661.Xr kevent 2 , 662.Xr kqueue 2 , 663.Xr linkat 2 , 664.Xr listen 2 , 665.Xr mmap 2 , 666.Xr mq_open 2 , 667.Xr open 2 , 668.Xr openat 2 , 669.Xr pdfork 2 , 670.Xr pdgetpid 2 , 671.Xr pdkill 2 , 672.Xr pdwait4 2 , 673.Xr pipe 2 , 674.Xr poll 2 , 675.Xr pread 2 , 676.Xr preadv 2 , 677.Xr pwrite 2 , 678.Xr pwritev 2 , 679.Xr read 2 , 680.Xr readv 2 , 681.Xr recv 2 , 682.Xr recvfrom 2 , 683.Xr recvmsg 2 , 684.Xr renameat 2 , 685.Xr sctp_peeloff 2 , 686.Xr select 2 , 687.Xr send 2 , 688.Xr sendmsg 2 , 689.Xr sendto 2 , 690.Xr setsockopt 2 , 691.Xr shm_open 2 , 692.Xr shutdown 2 , 693.Xr socket 2 , 694.Xr socketpair 2 , 695.Xr symlinkat 2 , 696.Xr unlinkat 2 , 697.Xr write 2 , 698.Xr writev 2 , 699.Xr acl_delete_fd_np 3 , 700.Xr acl_get_fd 3 , 701.Xr acl_get_fd_np 3 , 702.Xr acl_set_fd 3 , 703.Xr acl_set_fd_np 3 , 704.Xr acl_valid_fd_np 3 , 705.Xr mac_get_fd 3 , 706.Xr mac_set_fd 3 , 707.Xr sem_getvalue 3 , 708.Xr sem_post 3 , 709.Xr sem_trywait 3 , 710.Xr sem_wait 3 , 711.Xr capsicum 4 , 712.Xr snp 4 713.Sh HISTORY 714Support for capabilities and capabilities mode was developed as part of the 715.Tn TrustedBSD 716Project. 717.Sh AUTHORS 718.An -nosplit 719This manual page was created by 720.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 721under sponsorship from the FreeBSD Foundation based on the 722.Xr cap_new 2 723manual page by 724.An Robert Watson Aq Mt rwatson@FreeBSD.org . 725