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 .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 futimes 2
 276 and
 277 .Xr futimesat 2
 278 if the
 279 .Dv CAP_LOOKUP
 280 right is also present.
 281 .It Dv CAP_FUTIMESAT
 282 An alias to
 283 .Dv CAP_FUTIMES
 284 and
 285 .Dv CAP_LOOKUP .
 286 .It Dv CAP_GETPEERNAME
 287 Permit
 288 .Xr getpeername 2 .
 289 .It Dv CAP_GETSOCKNAME
 290 Permit
 291 .Xr getsockname 2 .
 292 .It Dv CAP_GETSOCKOPT
 293 Permit
 294 .Xr getsockopt 2 .
 295 .It Dv CAP_IOCTL
 296 Permit
 297 .Xr ioctl 2 .
 298 Be aware that this system call has enormous scope, including potentially
 299 global scope for some objects.
 300 The list of permitted ioctl commands can be further limited with the
 301 .Xr cap_ioctls_limit 2
 302 system call.
 303 .It Dv CAP_KQUEUE
 304 An alias to
 305 .Dv CAP_KQUEUE_CHANGE
 306 and
 307 .Dv CAP_KQUEUE_EVENT .
 308 .It Dv CAP_KQUEUE_CHANGE
 309 Permit
 310 .Xr kevent 2
 311 on a
 312 .Xr kqueue 2
 313 descriptor that modifies list of monitored events (the
 314 .Fa changelist
 315 argument is non-NULL).
 316 .It Dv CAP_KQUEUE_EVENT
 317 Permit
 318 .Xr kevent 2
 319 on a
 320 .Xr kqueue 2
 321 descriptor that monitors events (the
 322 .Fa eventlist
 323 argument is non-NULL).
 324 .Dv CAP_EVENT
 325 is also required on file descriptors that will be monitored using
 326 .Xr kevent 2 .
 327 .It Dv CAP_LINKAT
 328 Permit
 329 .Xr linkat 2
 330 and
 331 .Xr renameat 2
 332 on the destination directory descriptor.
 333 This right includes the
 334 .Dv CAP_LOOKUP
 335 right.
 336 .It Dv CAP_LISTEN
 337 Permit
 338 .Xr listen 2 ;
 339 not much use (generally) without
 340 .Dv CAP_BIND .
 341 .It Dv CAP_LOOKUP
 342 Permit the file descriptor to be used as a starting directory for calls such as
 343 .Xr linkat 2 ,
 344 .Xr openat 2 ,
 345 and
 346 .Xr unlinkat 2 .
 347 .It Dv CAP_MAC_GET
 348 Permit
 349 .Xr mac_get_fd 3 .
 350 .It Dv CAP_MAC_SET
 351 Permit
 352 .Xr mac_set_fd 3 .
 353 .It Dv CAP_MKDIRAT
 354 Permit
 355 .Xr mkdirat 2 .
 356 This right includes the
 357 .Dv CAP_LOOKUP
 358 right.
 359 .It Dv CAP_MKFIFOAT
 360 Permit
 361 .Xr mkfifoat 2 .
 362 This right includes the
 363 .Dv CAP_LOOKUP
 364 right.
 365 .It Dv CAP_MKNODAT
 366 Permit
 367 .Xr mknodat 2 .
 368 This right includes the
 369 .Dv CAP_LOOKUP
 370 right.
 371 .It Dv CAP_MMAP
 372 Permit
 373 .Xr mmap 2
 374 with the
 375 .Dv PROT_NONE
 376 protection.
 377 .It Dv CAP_MMAP_R
 378 Permit
 379 .Xr mmap 2
 380 with the
 381 .Dv PROT_READ
 382 protection.
 383 This right includes the
 384 .Dv CAP_READ
 385 and
 386 .Dv CAP_SEEK
 387 rights.
 388 .It Dv CAP_MMAP_RW
 389 An alias to
 390 .Dv CAP_MMAP_R
 391 and
 392 .Dv CAP_MMAP_W .
 393 .It Dv CAP_MMAP_RWX
 394 An alias to
 395 .Dv CAP_MMAP_R ,
 396 .Dv CAP_MMAP_W
 397 and
 398 .Dv CAP_MMAP_X .
 399 .It Dv CAP_MMAP_RX
 400 An alias to
 401 .Dv CAP_MMAP_R
 402 and
 403 .Dv CAP_MMAP_X .
 404 .It Dv CAP_MMAP_W
 405 Permit
 406 .Xr mmap 2
 407 with the
 408 .Dv PROT_WRITE
 409 protection.
 410 This right includes the
 411 .Dv CAP_WRITE
 412 and
 413 .Dv CAP_SEEK
 414 rights.
 415 .It Dv CAP_MMAP_WX
 416 An alias to
 417 .Dv CAP_MMAP_W
 418 and
 419 .Dv CAP_MMAP_X .
 420 .It Dv CAP_MMAP_X
 421 Permit
 422 .Xr mmap 2
 423 with the
 424 .Dv PROT_EXEC
 425 protection.
 426 This right includes the
 427 .Dv CAP_SEEK
 428 right.
 429 .It Dv CAP_PDGETPID
 430 Permit
 431 .Xr pdgetpid 2 .
 432 .It Dv CAP_PDKILL
 433 Permit
 434 .Xr pdkill 2 .
 435 .It Dv CAP_PDWAIT
 436 Permit
 437 .Xr pdwait4 2 .
 438 .It Dv CAP_PEELOFF
 439 Permit
 440 .Xr sctp_peeloff 2 .
 441 .It Dv CAP_PREAD
 442 An alias to
 443 .Dv CAP_READ
 444 and
 445 .Dv CAP_SEEK .
 446 .It Dv CAP_PWRITE
 447 An alias to
 448 .Dv CAP_SEEK
 449 and
 450 .Dv CAP_WRITE .
 451 .It Dv CAP_READ
 452 Permit
 453 .Xr aio_read 2
 454 .Dv ( CAP_SEEK
 455 is also required),
 456 .Xr openat 2
 457 with 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
 466 is also required),
 467 .Xr preadv 2
 468 .Dv ( CAP_SEEK
 469 is also required) and related system calls.
 470 .It Dv CAP_RECV
 471 An alias to
 472 .Dv CAP_READ .
 473 .It Dv CAP_RENAMEAT
 474 Permit
 475 .Xr renameat 2 .
 476 This right is required on the source directory descriptor.
 477 This right includes the
 478 .Dv CAP_LOOKUP
 479 right.
 480 .It Dv CAP_SEEK
 481 Permit operations that seek on the file descriptor, such as
 482 .Xr lseek 2 ,
 483 but also required for I/O system calls that can read or write at any position
 484 in the file, such as
 485 .Xr pread 2
 486 and
 487 .Xr pwrite 2 .
 488 .It Dv CAP_SEM_GETVALUE
 489 Permit
 490 .Xr sem_getvalue 3 .
 491 .It Dv CAP_SEM_POST
 492 Permit
 493 .Xr sem_post 3 .
 494 .It Dv CAP_SEM_WAIT
 495 Permit
 496 .Xr sem_wait 3
 497 and
 498 .Xr sem_trywait 3 .
 499 .It Dv CAP_SEND
 500 An alias to
 501 .Dv CAP_WRITE .
 502 .It Dv CAP_SETSOCKOPT
 503 Permit
 504 .Xr setsockopt 2 ;
 505 this controls various aspects of socket behavior and may affect binding,
 506 connecting, and other behaviors with global scope.
 507 .It Dv CAP_SHUTDOWN
 508 Permit explicit
 509 .Xr shutdown 2 ;
 510 closing the socket will also generally shut down any connections on it.
 511 .It Dv CAP_SYMLINKAT
 512 Permit
 513 .Xr symlinkat 2 .
 514 This right includes the
 515 .Dv CAP_LOOKUP
 516 right.
 517 .It Dv CAP_TTYHOOK
 518 Allow configuration of TTY hooks, such as
 519 .Xr snp 4 ,
 520 on the file descriptor.
 521 .It Dv CAP_UNLINKAT
 522 Permit
 523 .Xr unlinkat 2
 524 and
 525 .Xr renameat 2 .
 526 This right is only required for
 527 .Xr renameat 2
 528 on the destination directory descriptor if the destination object already
 529 exists and will be removed by the rename.
 530 This right includes the
 531 .Dv CAP_LOOKUP
 532 right.
 533 .It Dv CAP_WRITE
 534 Allow
 535 .Xr aio_write 2 ,
 536 .Xr openat 2
 537 with
 538 .Dv O_WRONLY
 539 and
 540 .Dv O_APPEND
 541 flags 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
 549 and related system calls.
 550 For
 551 .Xr sendto 2
 552 with a non-NULL connection address,
 553 .Dv CAP_CONNECT
 554 is also required.
 555 For
 556 .Xr openat 2
 557 with the
 558 .Dv O_WRONLY
 559 flag, but without the
 560 .Dv O_APPEND
 561 flag,
 562 .Dv CAP_SEEK
 563 is also required.
 564 For
 565 .Xr aio_write 2 ,
 566 .Xr pwrite 2
 567 and
 568 .Xr pwritev 2
 569 .Dv CAP_SEEK
 570 is 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
 664 Support for capabilities and capabilities mode was developed as part of the
 665 .Tn TrustedBSD
 666 Project.
 667 .Sh AUTHORS
 668 .An -nosplit
 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 the
 672 .Xr cap_new 2
 673 manual page by
 674 .An "Robert Watson" Aq rwatson@FreeBSD.org .