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