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