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