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