]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/rights.4
Merge ^/head r344178 through r344512.
[FreeBSD/FreeBSD.git] / 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 April 30, 2018
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_RENAMEAT_SOURCE
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 When not in capabilities mode, permit
98 .Xr bind 2
99 and
100 .Xr bindat 2
101 with special value
102 .Dv AT_FDCWD
103 in the
104 .Fa fd
105 parameter.
106 Note that sockets can also become bound implicitly as a result of
107 .Xr connect 2
108 or
109 .Xr send 2 ,
110 and that socket options set with
111 .Xr setsockopt 2
112 may also affect binding behavior.
113 .It Dv CAP_BINDAT
114 Permit
115 .Xr bindat 2 .
116 This right has to be present on the directory descriptor.
117 This right includes the
118 .Dv CAP_LOOKUP
119 right.
120 .It Dv CAP_CHFLAGSAT
121 An alias to
122 .Dv CAP_FCHFLAGS
123 and
124 .Dv CAP_LOOKUP .
125 .It Dv CAP_CONNECT
126 When not in capabilities mode, permit
127 .Xr connect 2
128 and
129 .Xr connectat 2
130 with special value
131 .Dv AT_FDCWD
132 in the
133 .Fa fd
134 parameter.
135 This right is also required for
136 .Xr sendto 2
137 with a non-NULL destination address.
138 .It Dv CAP_CONNECTAT
139 Permit
140 .Xr connectat 2 .
141 This right has to be present on the directory descriptor.
142 This right includes the
143 .Dv CAP_LOOKUP
144 right.
145 .It Dv CAP_CREATE
146 Permit
147 .Xr openat 2
148 with the
149 .Dv O_CREAT
150 flag.
151 .It Dv CAP_EVENT
152 Permit
153 .Xr select 2 ,
154 .Xr poll 2 ,
155 and
156 .Xr kevent 2
157 to be used in monitoring the file descriptor for events.
158 .It Dv CAP_EXTATTR_DELETE
159 Permit
160 .Xr extattr_delete_fd 2 .
161 .It Dv CAP_EXTATTR_GET
162 Permit
163 .Xr extattr_get_fd 2 .
164 .It Dv CAP_EXTATTR_LIST
165 Permit
166 .Xr extattr_list_fd 2 .
167 .It Dv CAP_EXTATTR_SET
168 Permit
169 .Xr extattr_set_fd 2 .
170 .It Dv CAP_FCHDIR
171 Permit
172 .Xr fchdir 2 .
173 .It Dv CAP_FCHFLAGS
174 Permit
175 .Xr fchflags 2
176 and
177 .Xr chflagsat 2
178 if the
179 .Dv CAP_LOOKUP
180 right is also present.
181 .It Dv CAP_FCHMOD
182 Permit
183 .Xr fchmod 2
184 and
185 .Xr fchmodat 2
186 if the
187 .Dv CAP_LOOKUP
188 right is also present.
189 .It Dv CAP_FCHMODAT
190 An alias to
191 .Dv CAP_FCHMOD
192 and
193 .Dv CAP_LOOKUP .
194 .It Dv CAP_FCHOWN
195 Permit
196 .Xr fchown 2
197 and
198 .Xr fchownat 2
199 if the
200 .Dv CAP_LOOKUP
201 right is also present.
202 .It Dv CAP_FCHOWNAT
203 An alias to
204 .Dv CAP_FCHOWN
205 and
206 .Dv CAP_LOOKUP .
207 .It Dv CAP_FCNTL
208 Permit
209 .Xr fcntl 2 .
210 Note that only the
211 .Dv F_GETFL ,
212 .Dv F_SETFL ,
213 .Dv F_GETOWN
214 and
215 .Dv F_SETOWN
216 commands require this capability right.
217 Also note that the list of permitted commands can be further limited with the
218 .Xr cap_fcntls_limit 2
219 system call.
220 .It Dv CAP_FEXECVE
221 Permit
222 .Xr fexecve 2
223 and
224 .Xr openat 2
225 with the
226 .Dv O_EXEC
227 flag;
228 .Dv CAP_READ
229 is also required.
230 .It Dv CAP_FLOCK
231 Permit
232 .Xr flock 2 ,
233 .Xr fcntl 2
234 (with
235 .Dv F_GETLK ,
236 .Dv F_SETLK ,
237 .Dv F_SETLKW
238 or
239 .Dv F_SETLK_REMOTE
240 flag) and
241 .Xr openat 2
242 (with
243 .Dv O_EXLOCK
244 or
245 .Dv O_SHLOCK
246 flag).
247 .It Dv CAP_FPATHCONF
248 Permit
249 .Xr fpathconf 2 .
250 .It Dv CAP_FSCK
251 Permit UFS background-fsck operations on the descriptor.
252 .It Dv CAP_FSTAT
253 Permit
254 .Xr fstat 2
255 and
256 .Xr fstatat 2
257 if the
258 .Dv CAP_LOOKUP
259 right is also present.
260 .It Dv CAP_FSTATAT
261 An alias to
262 .Dv CAP_FSTAT
263 and
264 .Dv CAP_LOOKUP .
265 .It Dv CAP_FSTATFS
266 Permit
267 .Xr fstatfs 2 .
268 .It Dv CAP_FSYNC
269 Permit
270 .Xr aio_fsync 2 ,
271 .Xr fdatasync 2 ,
272 .Xr fsync 2
273 and
274 .Xr openat 2
275 with
276 .Dv O_FSYNC
277 or
278 .Dv O_SYNC
279 flag.
280 .It Dv CAP_FTRUNCATE
281 Permit
282 .Xr ftruncate 2
283 and
284 .Xr openat 2
285 with the
286 .Dv O_TRUNC
287 flag.
288 .It Dv CAP_FUTIMES
289 Permit
290 .Xr futimens 2
291 and
292 .Xr futimes 2 ,
293 and permit
294 .Xr futimesat 2
295 and
296 .Xr utimensat 2
297 if the
298 .Dv CAP_LOOKUP
299 right is also present.
300 .It Dv CAP_FUTIMESAT
301 An alias to
302 .Dv CAP_FUTIMES
303 and
304 .Dv CAP_LOOKUP .
305 .It Dv CAP_GETPEERNAME
306 Permit
307 .Xr getpeername 2 .
308 .It Dv CAP_GETSOCKNAME
309 Permit
310 .Xr getsockname 2 .
311 .It Dv CAP_GETSOCKOPT
312 Permit
313 .Xr getsockopt 2 .
314 .It Dv CAP_IOCTL
315 Permit
316 .Xr ioctl 2 .
317 Be aware that this system call has enormous scope, including potentially
318 global scope for some objects.
319 The list of permitted ioctl commands can be further limited with the
320 .Xr cap_ioctls_limit 2
321 system call.
322 .It Dv CAP_KQUEUE
323 An alias to
324 .Dv CAP_KQUEUE_CHANGE
325 and
326 .Dv CAP_KQUEUE_EVENT .
327 .It Dv CAP_KQUEUE_CHANGE
328 Permit
329 .Xr kevent 2
330 on a
331 .Xr kqueue 2
332 descriptor that modifies list of monitored events (the
333 .Fa changelist
334 argument is non-NULL).
335 .It Dv CAP_KQUEUE_EVENT
336 Permit
337 .Xr kevent 2
338 on a
339 .Xr kqueue 2
340 descriptor that monitors events (the
341 .Fa eventlist
342 argument is non-NULL).
343 .Dv CAP_EVENT
344 is also required on file descriptors that will be monitored using
345 .Xr kevent 2 .
346 .It Dv CAP_LINKAT_SOURCE
347 Permit
348 .Xr linkat 2
349 on the source directory descriptor.
350 This right includes the
351 .Dv CAP_LOOKUP
352 right.
353 .Pp
354 Warning:
355 .Dv CAP_LINKAT_SOURCE
356 makes it possible to link files in a directory for which file
357 descriptors exist that have additional rights.
358 For example,
359 a file stored in a directory that does not allow
360 .Dv CAP_READ
361 may be linked in another directory that does allow
362 .Dv CAP_READ ,
363 thereby granting read access to a file that is otherwise unreadable.
364 .It Dv CAP_LINKAT_TARGET
365 Permit
366 .Xr linkat 2
367 on the target directory descriptor.
368 This right includes the
369 .Dv CAP_LOOKUP
370 right.
371 .It Dv CAP_LISTEN
372 Permit
373 .Xr listen 2 ;
374 not much use (generally) without
375 .Dv CAP_BIND .
376 .It Dv CAP_LOOKUP
377 Permit the file descriptor to be used as a starting directory for calls such as
378 .Xr linkat 2 ,
379 .Xr openat 2 ,
380 and
381 .Xr unlinkat 2 .
382 .It Dv CAP_MAC_GET
383 Permit
384 .Xr mac_get_fd 3 .
385 .It Dv CAP_MAC_SET
386 Permit
387 .Xr mac_set_fd 3 .
388 .It Dv CAP_MKDIRAT
389 Permit
390 .Xr mkdirat 2 .
391 This right includes the
392 .Dv CAP_LOOKUP
393 right.
394 .It Dv CAP_MKFIFOAT
395 Permit
396 .Xr mkfifoat 2 .
397 This right includes the
398 .Dv CAP_LOOKUP
399 right.
400 .It Dv CAP_MKNODAT
401 Permit
402 .Xr mknodat 2 .
403 This right includes the
404 .Dv CAP_LOOKUP
405 right.
406 .It Dv CAP_MMAP
407 Permit
408 .Xr mmap 2
409 with the
410 .Dv PROT_NONE
411 protection.
412 .It Dv CAP_MMAP_R
413 Permit
414 .Xr mmap 2
415 with the
416 .Dv PROT_READ
417 protection.
418 This right includes the
419 .Dv CAP_READ
420 and
421 .Dv CAP_SEEK
422 rights.
423 .It Dv CAP_MMAP_RW
424 An alias to
425 .Dv CAP_MMAP_R
426 and
427 .Dv CAP_MMAP_W .
428 .It Dv CAP_MMAP_RWX
429 An alias to
430 .Dv CAP_MMAP_R ,
431 .Dv CAP_MMAP_W
432 and
433 .Dv CAP_MMAP_X .
434 .It Dv CAP_MMAP_RX
435 An alias to
436 .Dv CAP_MMAP_R
437 and
438 .Dv CAP_MMAP_X .
439 .It Dv CAP_MMAP_W
440 Permit
441 .Xr mmap 2
442 with the
443 .Dv PROT_WRITE
444 protection.
445 This right includes the
446 .Dv CAP_WRITE
447 and
448 .Dv CAP_SEEK
449 rights.
450 .It Dv CAP_MMAP_WX
451 An alias to
452 .Dv CAP_MMAP_W
453 and
454 .Dv CAP_MMAP_X .
455 .It Dv CAP_MMAP_X
456 Permit
457 .Xr mmap 2
458 with the
459 .Dv PROT_EXEC
460 protection.
461 This right includes the
462 .Dv CAP_SEEK
463 right.
464 .It Dv CAP_PDGETPID
465 Permit
466 .Xr pdgetpid 2 .
467 .It Dv CAP_PDKILL
468 Permit
469 .Xr pdkill 2 .
470 .It Dv CAP_PDWAIT
471 Permit
472 .Xr pdwait4 2 .
473 .It Dv CAP_PEELOFF
474 Permit
475 .Xr sctp_peeloff 2 .
476 .It Dv CAP_PREAD
477 An alias to
478 .Dv CAP_READ
479 and
480 .Dv CAP_SEEK .
481 .It Dv CAP_PWRITE
482 An alias to
483 .Dv CAP_SEEK
484 and
485 .Dv CAP_WRITE .
486 .It Dv CAP_READ
487 Permit
488 .Xr aio_read 2
489 .Dv ( CAP_SEEK
490 is also required),
491 .Xr openat 2
492 with the
493 .Dv O_RDONLY flag,
494 .Xr read 2 ,
495 .Xr readv 2 ,
496 .Xr recv 2 ,
497 .Xr recvfrom 2 ,
498 .Xr recvmsg 2 ,
499 .Xr pread 2
500 .Dv ( CAP_SEEK
501 is also required),
502 .Xr preadv 2
503 .Dv ( CAP_SEEK
504 is also required) and related system calls.
505 .It Dv CAP_RECV
506 An alias to
507 .Dv CAP_READ .
508 .It Dv CAP_RENAMEAT_SOURCE
509 Permit
510 .Xr renameat 2
511 on the source directory descriptor.
512 This right includes the
513 .Dv CAP_LOOKUP
514 right.
515 .Pp
516 Warning:
517 .Dv CAP_RENAMEAT_SOURCE
518 makes it possible to move files to a directory for which file
519 descriptors exist that have additional rights.
520 For example,
521 a file stored in a directory that does not allow
522 .Dv CAP_READ
523 may be moved to another directory that does allow
524 .Dv CAP_READ ,
525 thereby granting read access to a file that is otherwise unreadable.
526 .It Dv CAP_RENAMEAT_TARGET
527 Permit
528 .Xr renameat 2
529 on the target directory descriptor.
530 This right includes the
531 .Dv CAP_LOOKUP
532 right.
533 .It Dv CAP_SEEK
534 Permit operations that seek on the file descriptor, such as
535 .Xr lseek 2 ,
536 but also required for I/O system calls that can read or write at any position
537 in the file, such as
538 .Xr pread 2
539 and
540 .Xr pwrite 2 .
541 .It Dv CAP_SEM_GETVALUE
542 Permit
543 .Xr sem_getvalue 3 .
544 .It Dv CAP_SEM_POST
545 Permit
546 .Xr sem_post 3 .
547 .It Dv CAP_SEM_WAIT
548 Permit
549 .Xr sem_wait 3
550 and
551 .Xr sem_trywait 3 .
552 .It Dv CAP_SEND
553 An alias to
554 .Dv CAP_WRITE .
555 .It Dv CAP_SETSOCKOPT
556 Permit
557 .Xr setsockopt 2 ;
558 this controls various aspects of socket behavior and may affect binding,
559 connecting, and other behaviors with global scope.
560 .It Dv CAP_SHUTDOWN
561 Permit explicit
562 .Xr shutdown 2 ;
563 closing the socket will also generally shut down any connections on it.
564 .It Dv CAP_SYMLINKAT
565 Permit
566 .Xr symlinkat 2 .
567 This right includes the
568 .Dv CAP_LOOKUP
569 right.
570 .It Dv CAP_TTYHOOK
571 Allow configuration of TTY hooks, such as
572 .Xr snp 4 ,
573 on the file descriptor.
574 .It Dv CAP_UNLINKAT
575 Permit
576 .Xr unlinkat 2
577 and
578 .Xr renameat 2 .
579 This right is only required for
580 .Xr renameat 2
581 on the destination directory descriptor if the destination object already
582 exists and will be removed by the rename.
583 This right includes the
584 .Dv CAP_LOOKUP
585 right.
586 .It Dv CAP_WRITE
587 Allow
588 .Xr aio_write 2 ,
589 .Xr openat 2
590 with
591 .Dv O_WRONLY
592 and
593 .Dv O_APPEND
594 flags set,
595 .Xr send 2 ,
596 .Xr sendmsg 2 ,
597 .Xr sendto 2 ,
598 .Xr write 2 ,
599 .Xr writev 2 ,
600 .Xr pwrite 2 ,
601 .Xr pwritev 2
602 and related system calls.
603 For
604 .Xr sendto 2
605 with a non-NULL connection address,
606 .Dv CAP_CONNECT
607 is also required.
608 For
609 .Xr openat 2
610 with the
611 .Dv O_WRONLY
612 flag, but without the
613 .Dv O_APPEND
614 flag,
615 .Dv CAP_SEEK
616 is also required.
617 For
618 .Xr aio_write 2 ,
619 .Xr pwrite 2
620 and
621 .Xr pwritev 2
622 .Dv CAP_SEEK
623 is also required.
624 .El
625 .Sh SEE ALSO
626 .Xr accept 2 ,
627 .Xr accept4 2 ,
628 .Xr aio_fsync 2 ,
629 .Xr aio_read 2 ,
630 .Xr aio_write 2 ,
631 .Xr bind 2 ,
632 .Xr bindat 2 ,
633 .Xr cap_enter 2 ,
634 .Xr cap_fcntls_limit 2 ,
635 .Xr cap_ioctls_limit 2 ,
636 .Xr cap_rights_limit 2 ,
637 .Xr chflagsat 2 ,
638 .Xr connect 2 ,
639 .Xr connectat 2 ,
640 .Xr extattr_delete_fd 2 ,
641 .Xr extattr_get_fd 2 ,
642 .Xr extattr_list_fd 2 ,
643 .Xr extattr_set_fd 2 ,
644 .Xr fchflags 2 ,
645 .Xr fchmod 2 ,
646 .Xr fchmodat 2 ,
647 .Xr fchown 2 ,
648 .Xr fchownat 2 ,
649 .Xr fcntl 2 ,
650 .Xr fexecve 2 ,
651 .Xr fhopen 2 ,
652 .Xr flock 2 ,
653 .Xr fpathconf 2 ,
654 .Xr fstat 2 ,
655 .Xr fstatat 2 ,
656 .Xr fstatfs 2 ,
657 .Xr fsync 2 ,
658 .Xr ftruncate 2 ,
659 .Xr futimes 2 ,
660 .Xr getpeername 2 ,
661 .Xr getsockname 2 ,
662 .Xr getsockopt 2 ,
663 .Xr ioctl 2 ,
664 .Xr kevent 2 ,
665 .Xr kqueue 2 ,
666 .Xr linkat 2 ,
667 .Xr listen 2 ,
668 .Xr mmap 2 ,
669 .Xr mq_open 2 ,
670 .Xr open 2 ,
671 .Xr openat 2 ,
672 .Xr pdfork 2 ,
673 .Xr pdgetpid 2 ,
674 .Xr pdkill 2 ,
675 .Xr pdwait4 2 ,
676 .Xr pipe 2 ,
677 .Xr poll 2 ,
678 .Xr pread 2 ,
679 .Xr preadv 2 ,
680 .Xr pwrite 2 ,
681 .Xr pwritev 2 ,
682 .Xr read 2 ,
683 .Xr readv 2 ,
684 .Xr recv 2 ,
685 .Xr recvfrom 2 ,
686 .Xr recvmsg 2 ,
687 .Xr renameat 2 ,
688 .Xr sctp_peeloff 2 ,
689 .Xr select 2 ,
690 .Xr send 2 ,
691 .Xr sendmsg 2 ,
692 .Xr sendto 2 ,
693 .Xr setsockopt 2 ,
694 .Xr shm_open 2 ,
695 .Xr shutdown 2 ,
696 .Xr socket 2 ,
697 .Xr socketpair 2 ,
698 .Xr symlinkat 2 ,
699 .Xr unlinkat 2 ,
700 .Xr write 2 ,
701 .Xr writev 2 ,
702 .Xr acl_delete_fd_np 3 ,
703 .Xr acl_get_fd 3 ,
704 .Xr acl_get_fd_np 3 ,
705 .Xr acl_set_fd 3 ,
706 .Xr acl_set_fd_np 3 ,
707 .Xr acl_valid_fd_np 3 ,
708 .Xr mac_get_fd 3 ,
709 .Xr mac_set_fd 3 ,
710 .Xr sem_getvalue 3 ,
711 .Xr sem_post 3 ,
712 .Xr sem_trywait 3 ,
713 .Xr sem_wait 3 ,
714 .Xr capsicum 4 ,
715 .Xr snp 4
716 .Sh HISTORY
717 Support for capabilities and capabilities mode was developed as part of the
718 .Tn TrustedBSD
719 Project.
720 .Sh AUTHORS
721 .An -nosplit
722 This manual page was created by
723 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
724 under sponsorship from the FreeBSD Foundation based on the
725 .Xr cap_new 2
726 manual page by
727 .An Robert Watson Aq Mt rwatson@FreeBSD.org .