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