xref: /freebsd/share/man/man4/rights.4 (revision 396c556d77189a5c474d35cec6f44a762e310b7d) 
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 17, 2016
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 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 fdatasync 2 ,
258.Xr fsync 2
259and
260.Xr openat 2
261with
262.Dv O_FSYNC
263or
264.Dv O_SYNC
265flag.
266.It Dv CAP_FTRUNCATE
267Permit
268.Xr ftruncate 2
269and
270.Xr openat 2
271with the
272.Dv O_TRUNC
273flag.
274.It Dv CAP_FUTIMES
275Permit
276.Xr futimens 2
277and
278.Xr futimes 2 ,
279and permit
280.Xr futimesat 2
281and
282.Xr utimensat 2
283if the
284.Dv CAP_LOOKUP
285right is also present.
286.It Dv CAP_FUTIMESAT
287An alias to
288.Dv CAP_FUTIMES
289and
290.Dv CAP_LOOKUP .
291.It Dv CAP_GETPEERNAME
292Permit
293.Xr getpeername 2 .
294.It Dv CAP_GETSOCKNAME
295Permit
296.Xr getsockname 2 .
297.It Dv CAP_GETSOCKOPT
298Permit
299.Xr getsockopt 2 .
300.It Dv CAP_IOCTL
301Permit
302.Xr ioctl 2 .
303Be aware that this system call has enormous scope, including potentially
304global scope for some objects.
305The list of permitted ioctl commands can be further limited with the
306.Xr cap_ioctls_limit 2
307system call.
308.It Dv CAP_KQUEUE
309An alias to
310.Dv CAP_KQUEUE_CHANGE
311and
312.Dv CAP_KQUEUE_EVENT .
313.It Dv CAP_KQUEUE_CHANGE
314Permit
315.Xr kevent 2
316on a
317.Xr kqueue 2
318descriptor that modifies list of monitored events (the
319.Fa changelist
320argument is non-NULL).
321.It Dv CAP_KQUEUE_EVENT
322Permit
323.Xr kevent 2
324on a
325.Xr kqueue 2
326descriptor that monitors events (the
327.Fa eventlist
328argument is non-NULL).
329.Dv CAP_EVENT
330is also required on file descriptors that will be monitored using
331.Xr kevent 2 .
332.It Dv CAP_LINKAT_SOURCE
333Permit
334.Xr linkat 2
335on the source directory descriptor.
336This right includes the
337.Dv CAP_LOOKUP
338right.
339.Pp
340Warning:
341.Dv CAP_LINKAT_SOURCE
342makes it possible to link files in a directory for which file
343descriptors exist that have additional rights.
344For example,
345a file stored in a directory that does not allow
346.Dv CAP_READ
347may be linked in another directory that does allow
348.Dv CAP_READ ,
349thereby granting read access to a file that is otherwise unreadable.
350.It Dv CAP_LINKAT_TARGET
351Permit
352.Xr linkat 2
353on the target directory descriptor.
354This right includes the
355.Dv CAP_LOOKUP
356right.
357.It Dv CAP_LISTEN
358Permit
359.Xr listen 2 ;
360not much use (generally) without
361.Dv CAP_BIND .
362.It Dv CAP_LOOKUP
363Permit the file descriptor to be used as a starting directory for calls such as
364.Xr linkat 2 ,
365.Xr openat 2 ,
366and
367.Xr unlinkat 2 .
368.It Dv CAP_MAC_GET
369Permit
370.Xr mac_get_fd 3 .
371.It Dv CAP_MAC_SET
372Permit
373.Xr mac_set_fd 3 .
374.It Dv CAP_MKDIRAT
375Permit
376.Xr mkdirat 2 .
377This right includes the
378.Dv CAP_LOOKUP
379right.
380.It Dv CAP_MKFIFOAT
381Permit
382.Xr mkfifoat 2 .
383This right includes the
384.Dv CAP_LOOKUP
385right.
386.It Dv CAP_MKNODAT
387Permit
388.Xr mknodat 2 .
389This right includes the
390.Dv CAP_LOOKUP
391right.
392.It Dv CAP_MMAP
393Permit
394.Xr mmap 2
395with the
396.Dv PROT_NONE
397protection.
398.It Dv CAP_MMAP_R
399Permit
400.Xr mmap 2
401with the
402.Dv PROT_READ
403protection.
404This right includes the
405.Dv CAP_READ
406and
407.Dv CAP_SEEK
408rights.
409.It Dv CAP_MMAP_RW
410An alias to
411.Dv CAP_MMAP_R
412and
413.Dv CAP_MMAP_W .
414.It Dv CAP_MMAP_RWX
415An alias to
416.Dv CAP_MMAP_R ,
417.Dv CAP_MMAP_W
418and
419.Dv CAP_MMAP_X .
420.It Dv CAP_MMAP_RX
421An alias to
422.Dv CAP_MMAP_R
423and
424.Dv CAP_MMAP_X .
425.It Dv CAP_MMAP_W
426Permit
427.Xr mmap 2
428with the
429.Dv PROT_WRITE
430protection.
431This right includes the
432.Dv CAP_WRITE
433and
434.Dv CAP_SEEK
435rights.
436.It Dv CAP_MMAP_WX
437An alias to
438.Dv CAP_MMAP_W
439and
440.Dv CAP_MMAP_X .
441.It Dv CAP_MMAP_X
442Permit
443.Xr mmap 2
444with the
445.Dv PROT_EXEC
446protection.
447This right includes the
448.Dv CAP_SEEK
449right.
450.It Dv CAP_PDGETPID
451Permit
452.Xr pdgetpid 2 .
453.It Dv CAP_PDKILL
454Permit
455.Xr pdkill 2 .
456.It Dv CAP_PDWAIT
457Permit
458.Xr pdwait4 2 .
459.It Dv CAP_PEELOFF
460Permit
461.Xr sctp_peeloff 2 .
462.It Dv CAP_PREAD
463An alias to
464.Dv CAP_READ
465and
466.Dv CAP_SEEK .
467.It Dv CAP_PWRITE
468An alias to
469.Dv CAP_SEEK
470and
471.Dv CAP_WRITE .
472.It Dv CAP_READ
473Permit
474.Xr aio_read 2
475.Dv ( CAP_SEEK
476is also required),
477.Xr openat 2
478with the
479.Dv O_RDONLY flag,
480.Xr read 2 ,
481.Xr readv 2 ,
482.Xr recv 2 ,
483.Xr recvfrom 2 ,
484.Xr recvmsg 2 ,
485.Xr pread 2
486.Dv ( CAP_SEEK
487is also required),
488.Xr preadv 2
489.Dv ( CAP_SEEK
490is also required) and related system calls.
491.It Dv CAP_RECV
492An alias to
493.Dv CAP_READ .
494.It Dv CAP_RENAMEAT_SOURCE
495Permit
496.Xr renameat 2
497on the source directory descriptor.
498This right includes the
499.Dv CAP_LOOKUP
500right.
501.Pp
502Warning:
503.Dv CAP_RENAMEAT_SOURCE
504makes it possible to move files to a directory for which file
505descriptors exist that have additional rights.
506For example,
507a file stored in a directory that does not allow
508.Dv CAP_READ
509may be moved to another directory that does allow
510.Dv CAP_READ ,
511thereby granting read access to a file that is otherwise unreadable.
512.It Dv CAP_RENAMEAT_TARGET
513Permit
514.Xr renameat 2
515on the target directory descriptor.
516This right includes the
517.Dv CAP_LOOKUP
518right.
519.It Dv CAP_SEEK
520Permit operations that seek on the file descriptor, such as
521.Xr lseek 2 ,
522but also required for I/O system calls that can read or write at any position
523in the file, such as
524.Xr pread 2
525and
526.Xr pwrite 2 .
527.It Dv CAP_SEM_GETVALUE
528Permit
529.Xr sem_getvalue 3 .
530.It Dv CAP_SEM_POST
531Permit
532.Xr sem_post 3 .
533.It Dv CAP_SEM_WAIT
534Permit
535.Xr sem_wait 3
536and
537.Xr sem_trywait 3 .
538.It Dv CAP_SEND
539An alias to
540.Dv CAP_WRITE .
541.It Dv CAP_SETSOCKOPT
542Permit
543.Xr setsockopt 2 ;
544this controls various aspects of socket behavior and may affect binding,
545connecting, and other behaviors with global scope.
546.It Dv CAP_SHUTDOWN
547Permit explicit
548.Xr shutdown 2 ;
549closing the socket will also generally shut down any connections on it.
550.It Dv CAP_SYMLINKAT
551Permit
552.Xr symlinkat 2 .
553This right includes the
554.Dv CAP_LOOKUP
555right.
556.It Dv CAP_TTYHOOK
557Allow configuration of TTY hooks, such as
558.Xr snp 4 ,
559on the file descriptor.
560.It Dv CAP_UNLINKAT
561Permit
562.Xr unlinkat 2
563and
564.Xr renameat 2 .
565This right is only required for
566.Xr renameat 2
567on the destination directory descriptor if the destination object already
568exists and will be removed by the rename.
569This right includes the
570.Dv CAP_LOOKUP
571right.
572.It Dv CAP_WRITE
573Allow
574.Xr aio_write 2 ,
575.Xr openat 2
576with
577.Dv O_WRONLY
578and
579.Dv O_APPEND
580flags set,
581.Xr send 2 ,
582.Xr sendmsg 2 ,
583.Xr sendto 2 ,
584.Xr write 2 ,
585.Xr writev 2 ,
586.Xr pwrite 2 ,
587.Xr pwritev 2
588and related system calls.
589For
590.Xr sendto 2
591with a non-NULL connection address,
592.Dv CAP_CONNECT
593is also required.
594For
595.Xr openat 2
596with the
597.Dv O_WRONLY
598flag, but without the
599.Dv O_APPEND
600flag,
601.Dv CAP_SEEK
602is also required.
603For
604.Xr aio_write 2 ,
605.Xr pwrite 2
606and
607.Xr pwritev 2
608.Dv CAP_SEEK
609is also required.
610.El
611.Sh SEE ALSO
612.Xr accept 2 ,
613.Xr accept4 2 ,
614.Xr aio_fsync 2 ,
615.Xr aio_read 2 ,
616.Xr aio_write 2 ,
617.Xr bind 2 ,
618.Xr bindat 2 ,
619.Xr cap_enter 2 ,
620.Xr cap_fcntls_limit 2 ,
621.Xr cap_ioctls_limit 2 ,
622.Xr cap_rights_limit 2 ,
623.Xr chflagsat 2 ,
624.Xr connect 2 ,
625.Xr connectat 2 ,
626.Xr extattr_delete_fd 2 ,
627.Xr extattr_get_fd 2 ,
628.Xr extattr_list_fd 2 ,
629.Xr extattr_set_fd 2 ,
630.Xr fchflags 2 ,
631.Xr fchmod 2 ,
632.Xr fchmodat 2 ,
633.Xr fchown 2 ,
634.Xr fchownat 2 ,
635.Xr fcntl 2 ,
636.Xr fexecve 2 ,
637.Xr fhopen 2 ,
638.Xr flock 2 ,
639.Xr fpathconf 2 ,
640.Xr fstat 2 ,
641.Xr fstatat 2 ,
642.Xr fstatfs 2 ,
643.Xr fsync 2 ,
644.Xr ftruncate 2 ,
645.Xr futimes 2 ,
646.Xr getpeername 2 ,
647.Xr getsockname 2 ,
648.Xr getsockopt 2 ,
649.Xr ioctl 2 ,
650.Xr kevent 2 ,
651.Xr kqueue 2 ,
652.Xr linkat 2 ,
653.Xr listen 2 ,
654.Xr mmap 2 ,
655.Xr mq_open 2 ,
656.Xr open 2 ,
657.Xr openat 2 ,
658.Xr pdfork 2 ,
659.Xr pdgetpid 2 ,
660.Xr pdkill 2 ,
661.Xr pdwait4 2 ,
662.Xr pipe 2 ,
663.Xr poll 2 ,
664.Xr pread 2 ,
665.Xr preadv 2 ,
666.Xr pwrite 2 ,
667.Xr pwritev 2 ,
668.Xr read 2 ,
669.Xr readv 2 ,
670.Xr recv 2 ,
671.Xr recvfrom 2 ,
672.Xr recvmsg 2 ,
673.Xr renameat 2 ,
674.Xr sctp_peeloff 2 ,
675.Xr select 2 ,
676.Xr send 2 ,
677.Xr sendmsg 2 ,
678.Xr sendto 2 ,
679.Xr setsockopt 2 ,
680.Xr shm_open 2 ,
681.Xr shutdown 2 ,
682.Xr socket 2 ,
683.Xr socketpair 2 ,
684.Xr symlinkat 2 ,
685.Xr unlinkat 2 ,
686.Xr write 2 ,
687.Xr writev 2 ,
688.Xr acl_delete_fd_np 3 ,
689.Xr acl_get_fd 3 ,
690.Xr acl_get_fd_np 3 ,
691.Xr acl_set_fd 3 ,
692.Xr acl_set_fd_np 3 ,
693.Xr acl_valid_fd_np 3 ,
694.Xr mac_get_fd 3 ,
695.Xr mac_set_fd 3 ,
696.Xr sem_getvalue 3 ,
697.Xr sem_post 3 ,
698.Xr sem_trywait 3 ,
699.Xr sem_wait 3 ,
700.Xr capsicum 4 ,
701.Xr snp 4
702.Sh HISTORY
703Support for capabilities and capabilities mode was developed as part of the
704.Tn TrustedBSD
705Project.
706.Sh AUTHORS
707.An -nosplit
708This manual page was created by
709.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
710under sponsorship from the FreeBSD Foundation based on the
711.Xr cap_new 2
712manual page by
713.An Robert Watson Aq Mt rwatson@FreeBSD.org .
714