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 September 23, 2013 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 futimes 2 276and 277.Xr futimesat 2 278if the 279.Dv CAP_LOOKUP 280right is also present. 281.It Dv CAP_FUTIMESAT 282An alias to 283.Dv CAP_FUTIMES 284and 285.Dv CAP_LOOKUP . 286.It Dv CAP_GETPEERNAME 287Permit 288.Xr getpeername 2 . 289.It Dv CAP_GETSOCKNAME 290Permit 291.Xr getsockname 2 . 292.It Dv CAP_GETSOCKOPT 293Permit 294.Xr getsockopt 2 . 295.It Dv CAP_IOCTL 296Permit 297.Xr ioctl 2 . 298Be aware that this system call has enormous scope, including potentially 299global scope for some objects. 300The list of permitted ioctl commands can be further limited with the 301.Xr cap_ioctls_limit 2 302system call. 303.It Dv CAP_KQUEUE 304An alias to 305.Dv CAP_KQUEUE_CHANGE 306and 307.Dv CAP_KQUEUE_EVENT . 308.It Dv CAP_KQUEUE_CHANGE 309Permit 310.Xr kevent 2 311on a 312.Xr kqueue 2 313descriptor that modifies list of monitored events (the 314.Fa changelist 315argument is non-NULL). 316.It Dv CAP_KQUEUE_EVENT 317Permit 318.Xr kevent 2 319on a 320.Xr kqueue 2 321descriptor that monitors events (the 322.Fa eventlist 323argument is non-NULL). 324.Dv CAP_EVENT 325is also required on file descriptors that will be monitored using 326.Xr kevent 2 . 327.It Dv CAP_LINKAT 328Permit 329.Xr linkat 2 330and 331.Xr renameat 2 332on the destination directory descriptor. 333This right includes the 334.Dv CAP_LOOKUP 335right. 336.It Dv CAP_LISTEN 337Permit 338.Xr listen 2 ; 339not much use (generally) without 340.Dv CAP_BIND . 341.It Dv CAP_LOOKUP 342Permit the file descriptor to be used as a starting directory for calls such as 343.Xr linkat 2 , 344.Xr openat 2 , 345and 346.Xr unlinkat 2 . 347.It Dv CAP_MAC_GET 348Permit 349.Xr mac_get_fd 3 . 350.It Dv CAP_MAC_SET 351Permit 352.Xr mac_set_fd 3 . 353.It Dv CAP_MKDIRAT 354Permit 355.Xr mkdirat 2 . 356This right includes the 357.Dv CAP_LOOKUP 358right. 359.It Dv CAP_MKFIFOAT 360Permit 361.Xr mkfifoat 2 . 362This right includes the 363.Dv CAP_LOOKUP 364right. 365.It Dv CAP_MKNODAT 366Permit 367.Xr mknodat 2 . 368This right includes the 369.Dv CAP_LOOKUP 370right. 371.It Dv CAP_MMAP 372Permit 373.Xr mmap 2 374with the 375.Dv PROT_NONE 376protection. 377.It Dv CAP_MMAP_R 378Permit 379.Xr mmap 2 380with the 381.Dv PROT_READ 382protection. 383This right includes the 384.Dv CAP_READ 385and 386.Dv CAP_SEEK 387rights. 388.It Dv CAP_MMAP_RW 389An alias to 390.Dv CAP_MMAP_R 391and 392.Dv CAP_MMAP_W . 393.It Dv CAP_MMAP_RWX 394An alias to 395.Dv CAP_MMAP_R , 396.Dv CAP_MMAP_W 397and 398.Dv CAP_MMAP_X . 399.It Dv CAP_MMAP_RX 400An alias to 401.Dv CAP_MMAP_R 402and 403.Dv CAP_MMAP_X . 404.It Dv CAP_MMAP_W 405Permit 406.Xr mmap 2 407with the 408.Dv PROT_WRITE 409protection. 410This right includes the 411.Dv CAP_WRITE 412and 413.Dv CAP_SEEK 414rights. 415.It Dv CAP_MMAP_WX 416An alias to 417.Dv CAP_MMAP_W 418and 419.Dv CAP_MMAP_X . 420.It Dv CAP_MMAP_X 421Permit 422.Xr mmap 2 423with the 424.Dv PROT_EXEC 425protection. 426This right includes the 427.Dv CAP_SEEK 428right. 429.It Dv CAP_PDGETPID 430Permit 431.Xr pdgetpid 2 . 432.It Dv CAP_PDKILL 433Permit 434.Xr pdkill 2 . 435.It Dv CAP_PDWAIT 436Permit 437.Xr pdwait4 2 . 438.It Dv CAP_PEELOFF 439Permit 440.Xr sctp_peeloff 2 . 441.It Dv CAP_PREAD 442An alias to 443.Dv CAP_READ 444and 445.Dv CAP_SEEK . 446.It Dv CAP_PWRITE 447An alias to 448.Dv CAP_SEEK 449and 450.Dv CAP_WRITE . 451.It Dv CAP_READ 452Permit 453.Xr aio_read 2 454.Dv ( CAP_SEEK 455is also required), 456.Xr openat 2 457with the 458.Dv O_RDONLY flag, 459.Xr read 2 , 460.Xr readv 2 , 461.Xr recv 2 , 462.Xr recvfrom 2 , 463.Xr recvmsg 2 , 464.Xr pread 2 465.Dv ( CAP_SEEK 466is also required), 467.Xr preadv 2 468.Dv ( CAP_SEEK 469is also required) and related system calls. 470.It Dv CAP_RECV 471An alias to 472.Dv CAP_READ . 473.It Dv CAP_RENAMEAT 474Permit 475.Xr renameat 2 . 476This right is required on the source directory descriptor. 477This right includes the 478.Dv CAP_LOOKUP 479right. 480.It Dv CAP_SEEK 481Permit operations that seek on the file descriptor, such as 482.Xr lseek 2 , 483but also required for I/O system calls that can read or write at any position 484in the file, such as 485.Xr pread 2 486and 487.Xr pwrite 2 . 488.It Dv CAP_SEM_GETVALUE 489Permit 490.Xr sem_getvalue 3 . 491.It Dv CAP_SEM_POST 492Permit 493.Xr sem_post 3 . 494.It Dv CAP_SEM_WAIT 495Permit 496.Xr sem_wait 3 497and 498.Xr sem_trywait 3 . 499.It Dv CAP_SEND 500An alias to 501.Dv CAP_WRITE . 502.It Dv CAP_SETSOCKOPT 503Permit 504.Xr setsockopt 2 ; 505this controls various aspects of socket behavior and may affect binding, 506connecting, and other behaviors with global scope. 507.It Dv CAP_SHUTDOWN 508Permit explicit 509.Xr shutdown 2 ; 510closing the socket will also generally shut down any connections on it. 511.It Dv CAP_SYMLINKAT 512Permit 513.Xr symlinkat 2 . 514This right includes the 515.Dv CAP_LOOKUP 516right. 517.It Dv CAP_TTYHOOK 518Allow configuration of TTY hooks, such as 519.Xr snp 4 , 520on the file descriptor. 521.It Dv CAP_UNLINKAT 522Permit 523.Xr unlinkat 2 524and 525.Xr renameat 2 . 526This right is only required for 527.Xr renameat 2 528on the destination directory descriptor if the destination object already 529exists and will be removed by the rename. 530This right includes the 531.Dv CAP_LOOKUP 532right. 533.It Dv CAP_WRITE 534Allow 535.Xr aio_write 2 , 536.Xr openat 2 537with 538.Dv O_WRONLY 539and 540.Dv O_APPEND 541flags set, 542.Xr send 2 , 543.Xr sendmsg 2 , 544.Xr sendto 2 , 545.Xr write 2 , 546.Xr writev 2 , 547.Xr pwrite 2 , 548.Xr pwritev 2 549and related system calls. 550For 551.Xr sendto 2 552with a non-NULL connection address, 553.Dv CAP_CONNECT 554is also required. 555For 556.Xr openat 2 557with the 558.Dv O_WRONLY 559flag, but without the 560.Dv O_APPEND 561flag, 562.Dv CAP_SEEK 563is also required. 564For 565.Xr aio_write 2 , 566.Xr pwrite 2 567and 568.Xr pwritev 2 569.Dv CAP_SEEK 570is also required. 571.El 572.Sh SEE ALSO 573.Xr accept 2 , 574.Xr accept4 2 , 575.Xr aio_fsync 2 , 576.Xr aio_read 2 , 577.Xr aio_write 2 , 578.Xr bind 2 , 579.Xr bindat 2 , 580.Xr cap_enter 2 , 581.Xr cap_fcntls_limit 2 , 582.Xr cap_ioctls_limit 2 , 583.Xr cap_rights_limit 2 , 584.Xr chflagsat 2 , 585.Xr connect 2 , 586.Xr connectat 2 , 587.Xr extattr_delete_fd 2 , 588.Xr extattr_get_fd 2 , 589.Xr extattr_list_fd 2 , 590.Xr extattr_set_fd 2 , 591.Xr fchflags 2 , 592.Xr fchmod 2 , 593.Xr fchmodat 2 , 594.Xr fchown 2 , 595.Xr fchownat 2 , 596.Xr fcntl 2 , 597.Xr fexecve 2 , 598.Xr fhopen 2 , 599.Xr flock 2 , 600.Xr fpathconf 2 , 601.Xr fstat 2 , 602.Xr fstatat 2 , 603.Xr fstatfs 2 , 604.Xr fsync 2 , 605.Xr ftruncate 2 , 606.Xr futimes 2 , 607.Xr getpeername 2 , 608.Xr getsockname 2 , 609.Xr getsockopt 2 , 610.Xr ioctl 2 , 611.Xr kevent 2 , 612.Xr kqueue 2 , 613.Xr linkat 2 , 614.Xr listen 2 , 615.Xr mmap 2 , 616.Xr mq_open 2 , 617.Xr open 2 , 618.Xr openat 2 , 619.Xr pdfork 2 , 620.Xr pdgetpid 2 , 621.Xr pdkill 2 , 622.Xr pdwait4 2 , 623.Xr pipe 2 , 624.Xr poll 2 , 625.Xr pread 2 , 626.Xr preadv 2 , 627.Xr pwrite 2 , 628.Xr pwritev 2 , 629.Xr read 2 , 630.Xr readv 2 , 631.Xr recv 2 , 632.Xr recvfrom 2 , 633.Xr recvmsg 2 , 634.Xr renameat 2 , 635.Xr sctp_peeloff 2 , 636.Xr select 2 , 637.Xr send 2 , 638.Xr sendmsg 2 , 639.Xr sendto 2 , 640.Xr setsockopt 2 , 641.Xr shm_open 2 , 642.Xr shutdown 2 , 643.Xr socket 2 , 644.Xr socketpair 2 , 645.Xr symlinkat 2 , 646.Xr unlinkat 2 , 647.Xr write 2 , 648.Xr writev 2 , 649.Xr acl_delete_fd_np 3 , 650.Xr acl_get_fd 3 , 651.Xr acl_get_fd_np 3 , 652.Xr acl_set_fd 3 , 653.Xr acl_set_fd_np 3 , 654.Xr acl_valid_fd_np 3 , 655.Xr mac_get_fd 3 , 656.Xr mac_set_fd 3 , 657.Xr sem_getvalue 3 , 658.Xr sem_post 3 , 659.Xr sem_trywait 3 , 660.Xr sem_wait 3 , 661.Xr capsicum 4 , 662.Xr snp 4 663.Sh HISTORY 664Support for capabilities and capabilities mode was developed as part of the 665.Tn TrustedBSD 666Project. 667.Sh AUTHORS 668.An -nosplit 669This manual page was created by 670.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 671under sponsorship from the FreeBSD Foundation based on the 672.Xr cap_new 2 673manual page by 674.An Robert Watson Aq Mt rwatson@FreeBSD.org . 675