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