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 November 25, 2023
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_empty ,
37.Nm cap_rights_is_valid ,
38.Nm cap_rights_merge ,
39.Nm cap_rights_remove ,
40.Nm cap_rights_contains
41.Nd manage cap_rights_t structure
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/capsicum.h
46.Ft cap_rights_t *
47.Fn cap_rights_init "cap_rights_t *rights" "..."
48.Ft cap_rights_t *
49.Fn cap_rights_set "cap_rights_t *rights" "..."
50.Ft cap_rights_t *
51.Fn cap_rights_clear "cap_rights_t *rights" "..."
52.Ft bool
53.Fn cap_rights_is_set "const cap_rights_t *rights" "..."
54.Ft bool
55.Fn cap_rights_is_empty "const cap_rights_t *rights"
56.Ft bool
57.Fn cap_rights_is_valid "const cap_rights_t *rights"
58.Ft cap_rights_t *
59.Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
60.Ft cap_rights_t *
61.Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
62.Ft bool
63.Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
64.Sh DESCRIPTION
65The functions documented here allow to manage the
66.Vt cap_rights_t
67structure.
68.Pp
69Capability rights should be separated with comma when passed to the
70.Fn cap_rights_init ,
71.Fn cap_rights_set ,
72.Fn cap_rights_clear
73and
74.Fn cap_rights_is_set
75functions.
76For example:
77.Bd -literal
78cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
79.Ed
80.Pp
81The complete list of the capability rights can be found in the
82.Xr rights 4
83manual page.
84.Pp
85The
86.Fn cap_rights_init
87function initialize provided
88.Vt cap_rights_t
89structure.
90Only properly initialized structure can be passed to the remaining functions.
91For convenience the structure can be filled with capability rights instead of
92calling the
93.Fn cap_rights_set
94function later.
95For even more convenience pointer to the given structure is returned, so it can
96be directly passed to
97.Xr cap_rights_limit 2 :
98.Bd -literal
99cap_rights_t rights;
100
101if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
102	err(1, "Unable to limit capability rights");
103.Ed
104.Pp
105The
106.Fn cap_rights_set
107function adds the given capability rights to the given
108.Vt cap_rights_t
109structure.
110.Pp
111The
112.Fn cap_rights_clear
113function removes the given capability rights from the given
114.Vt cap_rights_t
115structure.
116.Pp
117The
118.Fn cap_rights_is_set
119function checks if all the given capability rights are set for the given
120.Vt cap_rights_t
121structure.
122.Pp
123The
124.Fn cap_rights_is_empty
125function checks if the
126.Fa rights
127structure is empty.
128.Pp
129The
130.Fn cap_rights_is_valid
131function verifies if the given
132.Vt cap_rights_t
133structure is valid.
134.Pp
135The
136.Fn cap_rights_merge
137function merges all capability rights present in the
138.Fa src
139structure into the
140.Fa dst
141structure.
142.Pp
143The
144.Fn cap_rights_remove
145function removes all capability rights present in the
146.Fa src
147structure from the
148.Fa dst
149structure.
150.Pp
151The
152.Fn cap_rights_contains
153function checks if the
154.Fa big
155structure contains all capability rights present in the
156.Fa little
157structure.
158.Sh RETURN VALUES
159The functions never fail.
160In case an invalid capability right or an invalid
161.Vt cap_rights_t
162structure is given as an argument, the program will be aborted.
163.Pp
164The
165.Fn cap_rights_init ,
166.Fn cap_rights_set
167and
168.Fn cap_rights_clear
169functions return pointer to the
170.Vt cap_rights_t
171structure given in the
172.Fa rights
173argument.
174.Pp
175The
176.Fn cap_rights_merge
177and
178.Fn cap_rights_remove
179functions return pointer to the
180.Vt cap_rights_t
181structure given in the
182.Fa dst
183argument.
184.Pp
185The
186.Fn cap_rights_is_set
187returns
188.Va true
189if all the given capability rights are set in the
190.Fa rights
191argument.
192.Pp
193The
194.Fn cap_rights_is_empty
195function returns
196.Va true
197if none of the capability rights are set in the
198.Fa rights
199structure.
200.Pp
201The
202.Fn cap_rights_is_valid
203function performs various checks to see if the given
204.Vt cap_rights_t
205structure is valid and returns
206.Va true
207if it is.
208.Pp
209The
210.Fn cap_rights_contains
211function returns
212.Va true
213if all capability rights set in the
214.Fa little
215structure are also present in the
216.Fa big
217structure.
218.Sh EXAMPLES
219The following example demonstrates how to prepare a
220.Vt cap_rights_t
221structure to be passed to the
222.Xr cap_rights_limit 2
223system call.
224.Bd -literal
225cap_rights_t rights;
226int fd;
227
228fd = open("/tmp/foo", O_RDWR);
229if (fd < 0)
230	err(1, "open() failed");
231
232cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
233
234if (allow_write_and_seek)
235	cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
236
237if (dont_allow_seek)
238	cap_rights_clear(&rights, CAP_SEEK);
239
240if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
241	err(1, "cap_rights_limit() failed");
242.Ed
243.Sh SEE ALSO
244.Xr cap_rights_limit 2 ,
245.Xr open 2 ,
246.Xr capsicum 4 ,
247.Xr rights 4
248.Sh HISTORY
249The functions
250.Fn cap_rights_init ,
251.Fn cap_rights_set ,
252.Fn cap_rights_clear ,
253.Fn cap_rights_is_set ,
254.Fn cap_rights_is_valid ,
255.Fn cap_rights_merge ,
256.Fn cap_rights_remove
257and
258.Fn cap_rights_contains
259first appeared in
260.Fx 8.3 .
261Support for capabilities and capabilities mode was developed as part of the
262.Tn TrustedBSD
263Project.
264.Sh AUTHORS
265This family of functions was created by
266.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
267under sponsorship from the FreeBSD Foundation.
268