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