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