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