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