lib/libc/sys/cap_rights_limit.2

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