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