lib/libc/sys/cap_new.2

   1 .\"
   2 .\" Copyright (c) 2008-2010 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed at the University of Cambridge Computer
   6 .\" Laboratory with support from a grant from Google, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd July 20, 2011
  32 .Dt CAP_NEW 2
  33 .Os
  34 .Sh NAME
  35 .Nm cap_new ,
  36 .Nm cap_getrights
  37 .Nd System calls to manipulate capabilities
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/capability.h
  42 .Ft int
  43 .Fn cap_new "int fd" "cap_rights_t rights"
  44 .Ft int
  45 .Fn cap_getrights "int fd" "cap_rights_t *rightsp"
  46 .Sh DESCRIPTION
  47 Capabilities are special file descriptors derived from an existing file
  48 descriptor, such as one returned by
  49 .Xr fhopen 2 ,
  50 .Xr kqueue 2 ,
  51 .Xr mq_open 2 ,
  52 .Xr open 2 ,
  53 .Xr pipe 2 ,
  54 .Xr shm_open 2 ,
  55 .Xr socket 2 ,
  56 or
  57 .Xr socketpair 2 ,
  58 but with a restricted set of permitted operations determined by a rights
  59 mask set when the capability is created.
  60 These restricted rights cannot be changed after the capability is created,
  61 although further capabilities with yet more restricted rights may be created
  62 from an existing capability.
  63 In every other sense, a capability behaves in the same way as the file
  64 descriptor it was created from.
  65 .Pp
  66 .Fn cap_new
  67 creates a new capability for the existing file descriptor
  68 .Fa fd ,
  69 and returns a file descriptor for it.
  70 Operations on the capability will be limited to those permitted by
  71 .Fa rights ,
  72 which is static for the lifetime of the capability.
  73 If
  74 .Fa fd
  75 refers to an existing capability, then
  76 .Fa rights
  77 must be equal to or a subset of the rights on that capability.
  78 As with
  79 .Xr dup 2
  80 and
  81 .Xr dup2 2 ,
  82 many properties are shared between the new capability and the existing file
  83 descriptor, including open file flags, blocking disposition, and file offset.
  84 Many applications will prefer to use the
  85 .Xr cap_limitfd 3
  86 library call, part of
  87 .Xr libcapsicum 3 ,
  88 as it offers a more convenient interface.
  89 .Pp
  90 .Fn cap_getrights
  91 queries the rights associated with the capability referred to by file
  92 descriptor
  93 .Fa fd .
  94 .Pp
  95 These system calls, when combined with
  96 .Xr cap_enter 2 ,
  97 may be used to construct process sandboxes with highly granular rights
  98 assignment.
  99 .Sh RIGHTS
 100 The following rights may be specified in a new capability rights mask:
 101 .Bl -tag -width CAP_EXTATTR_DELETE
 102 .It Dv CAP_ACCEPT
 103 Permit
 104 .Xr accept 2 .
 105 .It Dv CAP_ACL_CHECK
 106 Permit checking of an ACL on a file descriptor; there is no cross-reference
 107 for this system call.
 108 .It Dv CAP_ACL_DELETE
 109 Permit
 110 .Xr acl_delete_fd_np 3 .
 111 .It Dv CAP_ACL_GET
 112 Permit
 113 .Xr acl_get_fd 3
 114 and
 115 .Xr acl_get_fd_np 3 .
 116 .It Dv CAP_ACL_SET
 117 Permit
 118 .Xr acl_set_fd 3
 119 and
 120 .Xr acl_set_fd_np 3 .
 121 .It Dv CAP_BIND
 122 Permit
 123 .Xr bind 2 .
 124 Note that sockets can also become bound implicitly as a result of
 125 .Xr connect 2
 126 or
 127 .Xr send 2 ,
 128 and that socket options set with
 129 .Xr setsockopt 2
 130 may also affect binding behavior.
 131 .It Dv CAP_CONNECT
 132 Permit
 133 .Xr connect 2 ;
 134 also required for
 135 .Xr sendto 2
 136 with a non-NULL destination address.
 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_FEXECVE
 145 Permit
 146 .Xr fexecve 2 ;
 147 .Dv CAP_READ
 148 will also be required.
 149 .It Dv CAP_EXTATTR_DELETE
 150 Permit
 151 .Xr extattr_delete_fd 2 .
 152 .It Dv CAP_EXTATTR_GET
 153 Permit
 154 .Xr extattr_get_fd 2 .
 155 .It Dv CAP_EXTATTR_LIST
 156 Permit
 157 .Xr extattr_list_fd 2 .
 158 .It Dv CAP_EXTATTR_SET
 159 Permit
 160 .Xr extattr_set_fd 2 .
 161 .It Dv CAP_FCHDIR
 162 Permit
 163 .Xr fchdir 2 .
 164 .It Dv CAP_FCHFLAGS
 165 Permit
 166 .Xr fchflags 2 .
 167 .It Dv CAP_FCHMOD
 168 Permit
 169 .Xr fchmod 2 .
 170 .It Dv CAP_FCHOWN
 171 Permit
 172 .Xr fchown 2 .
 173 .It Dv CAP_FCNTL
 174 Permit
 175 .Xr fcntl 2 ;
 176 be aware that this call provides indirect access to other operations, such as
 177 .Xr flock 2 .
 178 .It Dv CAP_FLOCK
 179 Permit
 180 .Xr flock 2
 181 and related calls.
 182 .It Dv CAP_FPATHCONF
 183 Permit
 184 .Xr fpathconf 2 .
 185 .It Dv CAP_FSCK
 186 Permit UFS background-fsck operations on the descriptor.
 187 .It Dv CAP_FSTAT
 188 Permit
 189 .Xr fstat 2 .
 190 .It Dv CAP_FSTATFS
 191 Permit
 192 .Xr fstatfs 2 .
 193 .It Dv CAP_FSYNC
 194 Permit
 195 .Xr aio_fsync 2
 196 and
 197 .Xr fsync 2 .
 198 .Pp
 199 .It Dv CAP_FTRUNCATE
 200 Permit
 201 .Xr ftruncate 2 .
 202 .It Dv CAP_FUTIMES
 203 Permit
 204 .Xr futimes 2 .
 205 .It Dv CAP_GETPEERNAME
 206 Permit
 207 .Xr getpeername 2 .
 208 .It Dv CAP_GETSOCKNAME
 209 Permit
 210 .Xr getsockname 2 .
 211 .It Dv CAP_GETSOCKOPT
 212 Permit
 213 .Xr getsockopt 2 .
 214 .It Dv CAP_IOCTL
 215 Permit
 216 .Xr ioctl 2 .
 217 Be aware that this system call has enormous scope, including potentially
 218 global scope for some objects.
 219 .It Dv CAP_KEVENT
 220 Permit
 221 .Xr kevent 2 ;
 222 .Dv CAP_EVENT
 223 is also required on file descriptors that will be monitored using
 224 .Xr kevent 2 .
 225 .It Dv CAP_LISTEN
 226 Permit
 227 .Xr listen 2 ;
 228 not much use (generally) without
 229 .Dv CAP_BIND .
 230 .It Dv CAP_LOOKUP
 231 Permit the file descriptor to be used as a starting directory for calls such
 232 as
 233 .Xr linkat 2 ,
 234 .Xr openat 2 ,
 235 and
 236 .Xr unlinkat 2 .
 237 Note that these calls are not available in capability mode as they manipulate
 238 a global name space; see
 239 .Xr cap_enter 2
 240 for details.
 241 .It Dv CAP_MAC_GET
 242 Permit
 243 .Xr mac_get_fd 3 .
 244 .It Dv CAP_MAC_SET
 245 Permit
 246 .Xr mac_set_fd 3 .
 247 .It Dv CAP_MMAP
 248 Permit
 249 .Xr mmap 2 ;
 250 specific invocations may also require
 251 .Dv CAP_READ
 252 or
 253 .Dv CAP_WRITE .
 254 .Pp
 255 .It Dv CAP_PDGETPID
 256 Permit
 257 .Xr pdgetpid 2 .
 258 .It Dv CAP_PDKILL
 259 Permit
 260 .Xr pdkill 2 .
 261 .It Dv CAP_PDWAIT
 262 Permit
 263 .Xr pdwait4 2 .
 264 .It Dv CAP_PEELOFF
 265 Permit
 266 .Xr sctp_peeloff 2 .
 267 .It Dv CAP_READ
 268 Allow
 269 .Xr aio_read 2 ,
 270 .Xr pread 2 ,
 271 .Xr read 2 ,
 272 .Xr recv 2 ,
 273 .Xr recvfrom 2 ,
 274 .Xr recvmsg 2 ,
 275 and related system calls.
 276 .Pp
 277 For files and other seekable objects,
 278 .Dv CAP_SEEK
 279 may also be required.
 280 .It Dv CAP_REVOKE
 281 Permit
 282 .Xr frevoke 2
 283 in certain ABI compatibility modes that support this system call.
 284 .It Dv CAP_SEEK
 285 Permit operations that seek on the file descriptor, such as
 286 .Xr lseek 2 ,
 287 but also required for I/O system calls that modify the file offset, such as
 288 .Xr read 2
 289 and
 290 .Xr write 2 .
 291 .It Dv CAP_SEM_GETVALUE
 292 Permit
 293 .Xr sem_getvalue 3 .
 294 .It Dv CAP_SEM_POST
 295 Permit
 296 .Xr sem_post 3 .
 297 .It Dv CAP_SEM_WAIT
 298 Permit
 299 .Xr sem_wait 3
 300 and
 301 .Xr sem_trywait 3 .
 302 .It Dv CAP_SETSOCKOPT
 303 Permit
 304 .Xr setsockopt 2 ;
 305 this controls various aspects of socket behavior and may affect binding,
 306 connecting, and other behaviors with global scope.
 307 .It Dv CAP_SHUTDOWN
 308 Permit explicit
 309 .Xr shutdown 2 ;
 310 closing the socket will also generally shut down any connections on it.
 311 .It Dv CAP_TTYHOOK
 312 Allow configuration of TTY hooks, such as
 313 .Xr snp 4 ,
 314 on the file descriptor.
 315 .It Dv CAP_WRITE
 316 Allow
 317 .Xr aio_write 2 ,
 318 .Xr pwrite 2 ,
 319 .Xr send 2 ,
 320 .Xr sendmsg 2 ,
 321 .Xr sendto 2 ,
 322 .Xr write 2 ,
 323 and related system calls.
 324 .Pp
 325 For files and other seekable objects,
 326 .Dv CAP_SEEK
 327 may also be required.
 328 .Pp
 329 For
 330 .Xr sendto 2
 331 with a non-NULL connection address,
 332 .Dv CAP_CONNECT
 333 is also required.
 334 .El
 335 .Sh CAVEAT
 336 The
 337 .Fn cap_new
 338 system call and the capabilities it creates may be used to assign
 339 fine-grained rights to sandboxed processes running in capability mode.
 340 However, the semantics of objects accessed via file descriptors are complex,
 341 so caution should be exercised in passing object capabilities into sandboxes.
 342 .Sh RETURN VALUES
 343 If successful,
 344 .Fn cap_new
 345 returns a non-negative integer, termed a file descriptor.
 346 It returns -1 on failure, and sets
 347 .Va errno
 348 to indicate the error.
 349 .Pp
 350 .Rv -std cap_getrights
 351 .Sh ERRORS
 352 .Fn cap_new
 353 may return the following errors:
 354 .Bl -tag -width Er
 355 .It Bq Er EBADF
 356 The
 357 .Fa fd
 358 argument is not a valid active descriptor.
 359 .It Bq Er EINVAL
 360 An invalid right has been requested in
 361 .Fa rights .
 362 .It Bq Er EMFILE
 363 The process has already reached its limit for open file descriptors.
 364 .It Bq Er ENFILE
 365 The system file table is full.
 366 .It Bq Er EPERM
 367 .Fa rights
 368 contains requested rights not present in the current rights mask associated
 369 with the capability referenced by
 370 .Fa fd ,
 371 if any.
 372 .El
 373 .Pp
 374 .Fn cap_getrights
 375 may return the following errors:
 376 .Bl -tag -width Er
 377 .It Bq Er EBADF
 378 The
 379 .Fa fd
 380 argument is not a valid active descriptor.
 381 .It Bq Er EINVAL
 382 The
 383 .Fa fd
 384 argument is not a capability.
 385 .El
 386 .Sh SEE ALSO
 387 .Xr accept 2 ,
 388 .Xr aio_fsync 2 ,
 389 .Xr aio_read 2 ,
 390 .Xr aio_write 2 ,
 391 .Xr bind 2 ,
 392 .Xr cap_enter 2 ,
 393 .Xr connect 2 ,
 394 .Xr dup 2 ,
 395 .Xr dup2 2 ,
 396 .Xr extattr_delete_fd 2 ,
 397 .Xr extattr_get_fd 2 ,
 398 .Xr extattr_list_fd 2 ,
 399 .Xr extattr_set_fd 2 ,
 400 .Xr fchflags 2 ,
 401 .Xr fchown 2 ,
 402 .Xr fcntl 2 ,
 403 .Xr fexecve 2 ,
 404 .Xr fhopen 2 ,
 405 .Xr flock 2 ,
 406 .Xr fpathconf 2 ,
 407 .Xr fstat 2 ,
 408 .Xr fstatfs 2 ,
 409 .Xr fsync 2 ,
 410 .Xr ftruncate 2 ,
 411 .Xr futimes 2 ,
 412 .Xr getpeername 2 ,
 413 .Xr getsockname 2 ,
 414 .Xr getsockopt 2 ,
 415 .Xr ioctl 2 ,
 416 .Xr kevent 2 ,
 417 .Xr kqueue 2 ,
 418 .Xr linkat 2 ,
 419 .Xr listen 2 ,
 420 .Xr mmap 2 ,
 421 .Xr mq_open 2 ,
 422 .Xr open 2 ,
 423 .Xr openat 2 ,
 424 .Xr pdgetpid 2 ,
 425 .Xr pdkill 2 ,
 426 .Xr pdwait4 2 ,
 427 .Xr pipe 2 ,
 428 .Xr poll 2 ,
 429 .Xr pread 2 ,
 430 .Xr pwrite 2 ,
 431 .Xr read 2 ,
 432 .Xr recv 2 ,
 433 .Xr recvfrom 2 ,
 434 .Xr recvmsg 2 ,
 435 .Xr sctp_peeloff 2 ,
 436 .Xr select 2 ,
 437 .Xr send 2 ,
 438 .Xr sendmsg 2 ,
 439 .Xr sendto 2 ,
 440 .Xr setsockopt 2 ,
 441 .Xr shm_open 2 ,
 442 .Xr shutdown 2 ,
 443 .Xr socket 2 ,
 444 .Xr socketpair 2 ,
 445 .Xr unlinkat 2 ,
 446 .Xr write 2 ,
 447 .Xr acl_delete_fd_np 3 ,
 448 .Xr acl_get_fd 3 ,
 449 .Xr acl_get_fd_np 3 ,
 450 .Xr acl_set_fd_np 3 ,
 451 .Xr cap_limitfd 3 ,
 452 .Xr libcapsicum 3 ,
 453 .Xr mac_get_fd 3 ,
 454 .Xr mac_set_fd 3 ,
 455 .Xr sem_getvalue 3 ,
 456 .Xr sem_post 3 ,
 457 .Xr sem_trywait 3 ,
 458 .Xr sem_wait 3 ,
 459 .Xr capsicum 4 ,
 460 .Xr snp 4
 461 .Sh HISTORY
 462 Support for capabilities and capabilities mode was developed as part of the
 463 .Tn TrustedBSD
 464 Project.
 465 .Sh AUTHORS
 466 These functions and the capability facility were created by
 467 .An "Robert N. M. Watson"
 468 at the University of Cambridge Computer Laboratory with support from a grant
 469 from Google, Inc.
 470 .Sh BUGS
 471 This man page should list the set of permitted system calls more specifically
 472 for each capability right.
 473 .Pp
 474 Capability rights sometimes have unclear indirect impacts, which should be
 475 documented, or at least hinted at.