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