share/man/man4/rights.4

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