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