1.\"
2.\" Copyright (c) 2013 The FreeBSD Foundation
3.\"
4.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
5.\" from the FreeBSD Foundation.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd May 5, 2020
29.Dt CAP_RIGHTS_INIT 3
30.Os
31.Sh NAME
32.Nm cap_rights_init ,
33.Nm cap_rights_set ,
34.Nm cap_rights_clear ,
35.Nm cap_rights_is_set ,
36.Nm cap_rights_is_valid ,
37.Nm cap_rights_merge ,
38.Nm cap_rights_remove ,
39.Nm cap_rights_contains
40.Nd manage cap_rights_t structure
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/capsicum.h
45.Ft cap_rights_t *
46.Fn cap_rights_init "cap_rights_t *rights" "..."
47.Ft cap_rights_t *
48.Fn cap_rights_set "cap_rights_t *rights" "..."
49.Ft cap_rights_t *
50.Fn cap_rights_clear "cap_rights_t *rights" "..."
51.Ft bool
52.Fn cap_rights_is_set "const cap_rights_t *rights" "..."
53.Ft bool
54.Fn cap_rights_is_valid "const cap_rights_t *rights"
55.Ft cap_rights_t *
56.Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
57.Ft cap_rights_t *
58.Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
59.Ft bool
60.Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
61.Sh DESCRIPTION
62The functions documented here allow to manage the
63.Vt cap_rights_t
64structure.
65.Pp
66Capability rights should be separated with comma when passed to the
67.Fn cap_rights_init ,
68.Fn cap_rights_set ,
69.Fn cap_rights_clear
70and
71.Fn cap_rights_is_set
72functions.
73For example:
74.Bd -literal
75cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
76.Ed
77.Pp
78The complete list of the capability rights can be found in the
79.Xr rights 4
80manual page.
81.Pp
82The
83.Fn cap_rights_init
84function initialize provided
85.Vt cap_rights_t
86structure.
87Only properly initialized structure can be passed to the remaining functions.
88For convenience the structure can be filled with capability rights instead of
89calling the
90.Fn cap_rights_set
91function later.
92For even more convenience pointer to the given structure is returned, so it can
93be directly passed to
94.Xr cap_rights_limit 2 :
95.Bd -literal
96cap_rights_t rights;
97
98if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
99	err(1, "Unable to limit capability rights");
100.Ed
101.Pp
102The
103.Fn cap_rights_set
104function adds the given capability rights to the given
105.Vt cap_rights_t
106structure.
107.Pp
108The
109.Fn cap_rights_clear
110function removes the given capability rights from the given
111.Vt cap_rights_t
112structure.
113.Pp
114The
115.Fn cap_rights_is_set
116function checks if all the given capability rights are set for the given
117.Vt cap_rights_t
118structure.
119.Pp
120The
121.Fn cap_rights_is_valid
122function verifies if the given
123.Vt cap_rights_t
124structure is valid.
125.Pp
126The
127.Fn cap_rights_merge
128function merges all capability rights present in the
129.Fa src
130structure into the
131.Fa dst
132structure.
133.Pp
134The
135.Fn cap_rights_remove
136function removes all capability rights present in the
137.Fa src
138structure from the
139.Fa dst
140structure.
141.Pp
142The
143.Fn cap_rights_contains
144function checks if the
145.Fa big
146structure contains all capability rights present in the
147.Fa little
148structure.
149.Sh RETURN VALUES
150The functions never fail.
151In case an invalid capability right or an invalid
152.Vt cap_rights_t
153structure is given as an argument, the program will be aborted.
154.Pp
155The
156.Fn cap_rights_init ,
157.Fn cap_rights_set
158and
159.Fn cap_rights_clear
160functions return pointer to the
161.Vt cap_rights_t
162structure given in the
163.Fa rights
164argument.
165.Pp
166The
167.Fn cap_rights_merge
168and
169.Fn cap_rights_remove
170functions return pointer to the
171.Vt cap_rights_t
172structure given in the
173.Fa dst
174argument.
175.Pp
176The
177.Fn cap_rights_is_set
178returns
179.Va true
180if all the given capability rights are set in the
181.Fa rights
182argument.
183.Pp
184The
185.Fn cap_rights_is_valid
186function performs various checks to see if the given
187.Vt cap_rights_t
188structure is valid and returns
189.Va true
190if it is.
191.Pp
192The
193.Fn cap_rights_contains
194function returns
195.Va true
196if all capability rights set in the
197.Fa little
198structure are also present in the
199.Fa big
200structure.
201.Sh EXAMPLES
202The following example demonstrates how to prepare a
203.Vt cap_rights_t
204structure to be passed to the
205.Xr cap_rights_limit 2
206system call.
207.Bd -literal
208cap_rights_t rights;
209int fd;
210
211fd = open("/tmp/foo", O_RDWR);
212if (fd < 0)
213	err(1, "open() failed");
214
215cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
216
217if (allow_write_and_seek)
218	cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
219
220if (dont_allow_seek)
221	cap_rights_clear(&rights, CAP_SEEK);
222
223if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
224	err(1, "cap_rights_limit() failed");
225.Ed
226.Sh SEE ALSO
227.Xr cap_rights_limit 2 ,
228.Xr open 2 ,
229.Xr capsicum 4 ,
230.Xr rights 4
231.Sh HISTORY
232The functions
233.Fn cap_rights_init ,
234.Fn cap_rights_set ,
235.Fn cap_rights_clear ,
236.Fn cap_rights_is_set ,
237.Fn cap_rights_is_valid ,
238.Fn cap_rights_merge ,
239.Fn cap_rights_remove
240and
241.Fn cap_rights_contains
242first appeared in
243.Fx 8.3 .
244Support for capabilities and capabilities mode was developed as part of the
245.Tn TrustedBSD
246Project.
247.Sh AUTHORS
248This family of functions was created by
249.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
250under sponsorship from the FreeBSD Foundation.
251