]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/rights.4
disk(9): Fix a few mandoc related errors
[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 February 28, 2019
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_PEELOFF
471 Permit
472 .Xr sctp_peeloff 2 .
473 .It Dv CAP_PREAD
474 An alias to
475 .Dv CAP_READ
476 and
477 .Dv CAP_SEEK .
478 .It Dv CAP_PWRITE
479 An alias to
480 .Dv CAP_SEEK
481 and
482 .Dv CAP_WRITE .
483 .It Dv CAP_READ
484 Permit
485 .Xr aio_read 2
486 .Dv ( CAP_SEEK
487 is also required),
488 .Xr openat 2
489 with the
490 .Dv O_RDONLY flag,
491 .Xr read 2 ,
492 .Xr readv 2 ,
493 .Xr recv 2 ,
494 .Xr recvfrom 2 ,
495 .Xr recvmsg 2 ,
496 .Xr pread 2
497 .Dv ( CAP_SEEK
498 is also required),
499 .Xr preadv 2
500 .Dv ( CAP_SEEK
501 is also required) and related system calls.
502 .It Dv CAP_RECV
503 An alias to
504 .Dv CAP_READ .
505 .It Dv CAP_RENAMEAT_SOURCE
506 Permit
507 .Xr renameat 2
508 on the source directory descriptor.
509 This right includes the
510 .Dv CAP_LOOKUP
511 right.
512 .Pp
513 Warning:
514 .Dv CAP_RENAMEAT_SOURCE
515 makes it possible to move files to a directory for which file
516 descriptors exist that have additional rights.
517 For example,
518 a file stored in a directory that does not allow
519 .Dv CAP_READ
520 may be moved to another directory that does allow
521 .Dv CAP_READ ,
522 thereby granting read access to a file that is otherwise unreadable.
523 .It Dv CAP_RENAMEAT_TARGET
524 Permit
525 .Xr renameat 2
526 on the target directory descriptor.
527 This right includes the
528 .Dv CAP_LOOKUP
529 right.
530 .It Dv CAP_SEEK
531 Permit operations that seek on the file descriptor, such as
532 .Xr lseek 2 ,
533 but also required for I/O system calls that can read or write at any position
534 in the file, such as
535 .Xr pread 2
536 and
537 .Xr pwrite 2 .
538 .It Dv CAP_SEM_GETVALUE
539 Permit
540 .Xr sem_getvalue 3 .
541 .It Dv CAP_SEM_POST
542 Permit
543 .Xr sem_post 3 .
544 .It Dv CAP_SEM_WAIT
545 Permit
546 .Xr sem_wait 3
547 and
548 .Xr sem_trywait 3 .
549 .It Dv CAP_SEND
550 An alias to
551 .Dv CAP_WRITE .
552 .It Dv CAP_SETSOCKOPT
553 Permit
554 .Xr setsockopt 2 ;
555 this controls various aspects of socket behavior and may affect binding,
556 connecting, and other behaviors with global scope.
557 .It Dv CAP_SHUTDOWN
558 Permit explicit
559 .Xr shutdown 2 ;
560 closing the socket will also generally shut down any connections on it.
561 .It Dv CAP_SYMLINKAT
562 Permit
563 .Xr symlinkat 2 .
564 This right includes the
565 .Dv CAP_LOOKUP
566 right.
567 .It Dv CAP_TTYHOOK
568 Allow configuration of TTY hooks, such as
569 .Xr snp 4 ,
570 on the file descriptor.
571 .It Dv CAP_UNLINKAT
572 Permit
573 .Xr unlinkat 2
574 and
575 .Xr renameat 2 .
576 This right is only required for
577 .Xr renameat 2
578 on the destination directory descriptor if the destination object already
579 exists and will be removed by the rename.
580 This right includes the
581 .Dv CAP_LOOKUP
582 right.
583 .It Dv CAP_WRITE
584 Allow
585 .Xr aio_write 2 ,
586 .Xr openat 2
587 with
588 .Dv O_WRONLY
589 and
590 .Dv O_APPEND
591 flags set,
592 .Xr send 2 ,
593 .Xr sendmsg 2 ,
594 .Xr sendto 2 ,
595 .Xr write 2 ,
596 .Xr writev 2 ,
597 .Xr pwrite 2 ,
598 .Xr pwritev 2
599 and related system calls.
600 For
601 .Xr sendto 2
602 with a non-NULL connection address,
603 .Dv CAP_CONNECT
604 is also required.
605 For
606 .Xr openat 2
607 with the
608 .Dv O_WRONLY
609 flag, but without the
610 .Dv O_APPEND
611 flag,
612 .Dv CAP_SEEK
613 is also required.
614 For
615 .Xr aio_write 2 ,
616 .Xr pwrite 2
617 and
618 .Xr pwritev 2
619 .Dv CAP_SEEK
620 is also required.
621 .El
622 .Sh SEE ALSO
623 .Xr accept 2 ,
624 .Xr accept4 2 ,
625 .Xr aio_fsync 2 ,
626 .Xr aio_read 2 ,
627 .Xr aio_write 2 ,
628 .Xr bind 2 ,
629 .Xr bindat 2 ,
630 .Xr cap_enter 2 ,
631 .Xr cap_fcntls_limit 2 ,
632 .Xr cap_ioctls_limit 2 ,
633 .Xr cap_rights_limit 2 ,
634 .Xr chflagsat 2 ,
635 .Xr connect 2 ,
636 .Xr connectat 2 ,
637 .Xr extattr_delete_fd 2 ,
638 .Xr extattr_get_fd 2 ,
639 .Xr extattr_list_fd 2 ,
640 .Xr extattr_set_fd 2 ,
641 .Xr fchflags 2 ,
642 .Xr fchmod 2 ,
643 .Xr fchmodat 2 ,
644 .Xr fchown 2 ,
645 .Xr fchownat 2 ,
646 .Xr fcntl 2 ,
647 .Xr fexecve 2 ,
648 .Xr fhopen 2 ,
649 .Xr flock 2 ,
650 .Xr fpathconf 2 ,
651 .Xr fstat 2 ,
652 .Xr fstatat 2 ,
653 .Xr fstatfs 2 ,
654 .Xr fsync 2 ,
655 .Xr ftruncate 2 ,
656 .Xr futimes 2 ,
657 .Xr getpeername 2 ,
658 .Xr getsockname 2 ,
659 .Xr getsockopt 2 ,
660 .Xr ioctl 2 ,
661 .Xr kevent 2 ,
662 .Xr kqueue 2 ,
663 .Xr linkat 2 ,
664 .Xr listen 2 ,
665 .Xr mmap 2 ,
666 .Xr mq_open 2 ,
667 .Xr open 2 ,
668 .Xr openat 2 ,
669 .Xr pdfork 2 ,
670 .Xr pdgetpid 2 ,
671 .Xr pdkill 2 ,
672 .Xr pdwait4 2 ,
673 .Xr pipe 2 ,
674 .Xr poll 2 ,
675 .Xr pread 2 ,
676 .Xr preadv 2 ,
677 .Xr pwrite 2 ,
678 .Xr pwritev 2 ,
679 .Xr read 2 ,
680 .Xr readv 2 ,
681 .Xr recv 2 ,
682 .Xr recvfrom 2 ,
683 .Xr recvmsg 2 ,
684 .Xr renameat 2 ,
685 .Xr sctp_peeloff 2 ,
686 .Xr select 2 ,
687 .Xr send 2 ,
688 .Xr sendmsg 2 ,
689 .Xr sendto 2 ,
690 .Xr setsockopt 2 ,
691 .Xr shm_open 2 ,
692 .Xr shutdown 2 ,
693 .Xr socket 2 ,
694 .Xr socketpair 2 ,
695 .Xr symlinkat 2 ,
696 .Xr unlinkat 2 ,
697 .Xr write 2 ,
698 .Xr writev 2 ,
699 .Xr acl_delete_fd_np 3 ,
700 .Xr acl_get_fd 3 ,
701 .Xr acl_get_fd_np 3 ,
702 .Xr acl_set_fd 3 ,
703 .Xr acl_set_fd_np 3 ,
704 .Xr acl_valid_fd_np 3 ,
705 .Xr mac_get_fd 3 ,
706 .Xr mac_set_fd 3 ,
707 .Xr sem_getvalue 3 ,
708 .Xr sem_post 3 ,
709 .Xr sem_trywait 3 ,
710 .Xr sem_wait 3 ,
711 .Xr capsicum 4 ,
712 .Xr snp 4
713 .Sh HISTORY
714 Support for capabilities and capabilities mode was developed as part of the
715 .Tn TrustedBSD
716 Project.
717 .Sh AUTHORS
718 .An -nosplit
719 This manual page was created by
720 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
721 under sponsorship from the FreeBSD Foundation based on the
722 .Xr cap_new 2
723 manual page by
724 .An Robert Watson Aq Mt rwatson@FreeBSD.org .