1.\" 2.\" Copyright (c) 2013 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" This documentation was written by Pawel Jakub Dawidek under sponsorship 6.\" from the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd May 5, 2020 32.Dt CAP_RIGHTS_INIT 3 33.Os 34.Sh NAME 35.Nm cap_rights_init , 36.Nm cap_rights_set , 37.Nm cap_rights_clear , 38.Nm cap_rights_is_set , 39.Nm cap_rights_is_valid , 40.Nm cap_rights_merge , 41.Nm cap_rights_remove , 42.Nm cap_rights_contains 43.Nd manage cap_rights_t structure 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In sys/capsicum.h 48.Ft cap_rights_t * 49.Fn cap_rights_init "cap_rights_t *rights" "..." 50.Ft cap_rights_t * 51.Fn cap_rights_set "cap_rights_t *rights" "..." 52.Ft cap_rights_t * 53.Fn cap_rights_clear "cap_rights_t *rights" "..." 54.Ft bool 55.Fn cap_rights_is_set "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_valid 125function verifies if the given 126.Vt cap_rights_t 127structure is valid. 128.Pp 129The 130.Fn cap_rights_merge 131function merges all capability rights present in the 132.Fa src 133structure into the 134.Fa dst 135structure. 136.Pp 137The 138.Fn cap_rights_remove 139function removes all capability rights present in the 140.Fa src 141structure from the 142.Fa dst 143structure. 144.Pp 145The 146.Fn cap_rights_contains 147function checks if the 148.Fa big 149structure contains all capability rights present in the 150.Fa little 151structure. 152.Sh RETURN VALUES 153The functions never fail. 154In case an invalid capability right or an invalid 155.Vt cap_rights_t 156structure is given as an argument, the program will be aborted. 157.Pp 158The 159.Fn cap_rights_init , 160.Fn cap_rights_set 161and 162.Fn cap_rights_clear 163functions return pointer to the 164.Vt cap_rights_t 165structure given in the 166.Fa rights 167argument. 168.Pp 169The 170.Fn cap_rights_merge 171and 172.Fn cap_rights_remove 173functions return pointer to the 174.Vt cap_rights_t 175structure given in the 176.Fa dst 177argument. 178.Pp 179The 180.Fn cap_rights_is_set 181returns 182.Va true 183if all the given capability rights are set in the 184.Fa rights 185argument. 186.Pp 187The 188.Fn cap_rights_is_valid 189function performs various checks to see if the given 190.Vt cap_rights_t 191structure is valid and returns 192.Va true 193if it is. 194.Pp 195The 196.Fn cap_rights_contains 197function returns 198.Va true 199if all capability rights set in the 200.Fa little 201structure are also present in the 202.Fa big 203structure. 204.Sh EXAMPLES 205The following example demonstrates how to prepare a 206.Vt cap_rights_t 207structure to be passed to the 208.Xr cap_rights_limit 2 209system call. 210.Bd -literal 211cap_rights_t rights; 212int fd; 213 214fd = open("/tmp/foo", O_RDWR); 215if (fd < 0) 216 err(1, "open() failed"); 217 218cap_rights_init(&rights, CAP_FSTAT, CAP_READ); 219 220if (allow_write_and_seek) 221 cap_rights_set(&rights, CAP_WRITE, CAP_SEEK); 222 223if (dont_allow_seek) 224 cap_rights_clear(&rights, CAP_SEEK); 225 226if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS) 227 err(1, "cap_rights_limit() failed"); 228.Ed 229.Sh SEE ALSO 230.Xr cap_rights_limit 2 , 231.Xr open 2 , 232.Xr capsicum 4 , 233.Xr rights 4 234.Sh HISTORY 235The functions 236.Fn cap_rights_init , 237.Fn cap_rights_set , 238.Fn cap_rights_clear , 239.Fn cap_rights_is_set , 240.Fn cap_rights_is_valid , 241.Fn cap_rights_merge , 242.Fn cap_rights_remove 243and 244.Fn cap_rights_contains 245first appeared in 246.Fx 8.3 . 247Support for capabilities and capabilities mode was developed as part of the 248.Tn TrustedBSD 249Project. 250.Sh AUTHORS 251This family of functions was created by 252.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 253under sponsorship from the FreeBSD Foundation. 254