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