18269e767SBrooks Davis.\" 28269e767SBrooks Davis.\" Copyright (c) 2008-2010 Robert N. M. Watson 38269e767SBrooks Davis.\" Copyright (c) 2012-2013 The FreeBSD Foundation 48269e767SBrooks Davis.\" All rights reserved. 58269e767SBrooks Davis.\" 68269e767SBrooks Davis.\" This software was developed at the University of Cambridge Computer 78269e767SBrooks Davis.\" Laboratory with support from a grant from Google, Inc. 88269e767SBrooks Davis.\" 98269e767SBrooks Davis.\" Portions of this documentation were written by Pawel Jakub Dawidek 108269e767SBrooks Davis.\" under sponsorship from the FreeBSD Foundation. 118269e767SBrooks Davis.\" 128269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without 138269e767SBrooks Davis.\" modification, are permitted provided that the following conditions 148269e767SBrooks Davis.\" are met: 158269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright 168269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer. 178269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright 188269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer in the 198269e767SBrooks Davis.\" documentation and/or other materials provided with the distribution. 208269e767SBrooks Davis.\" 218269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 228269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 238269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 248269e767SBrooks Davis.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 258269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 268269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 278269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 288269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 298269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 308269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 318269e767SBrooks Davis.\" SUCH DAMAGE. 328269e767SBrooks Davis.\" 33d2893828SCismonX.Dd April 27, 2024 348269e767SBrooks Davis.Dt CAP_RIGHTS_LIMIT 2 358269e767SBrooks Davis.Os 368269e767SBrooks Davis.Sh NAME 378269e767SBrooks Davis.Nm cap_rights_limit 388269e767SBrooks Davis.Nd limit capability rights 398269e767SBrooks Davis.Sh LIBRARY 408269e767SBrooks Davis.Lb libc 418269e767SBrooks Davis.Sh SYNOPSIS 428269e767SBrooks Davis.In sys/capsicum.h 438269e767SBrooks Davis.Ft int 448269e767SBrooks Davis.Fn cap_rights_limit "int fd" "const cap_rights_t *rights" 458269e767SBrooks Davis.Sh DESCRIPTION 468269e767SBrooks DavisWhen a file descriptor is created by a function such as 478269e767SBrooks Davis.Xr fhopen 2 , 488269e767SBrooks Davis.Xr kqueue 2 , 498269e767SBrooks Davis.Xr mq_open 2 , 508269e767SBrooks Davis.Xr open 2 , 518269e767SBrooks Davis.Xr pdfork 2 , 528269e767SBrooks Davis.Xr pipe 2 , 538269e767SBrooks Davis.Xr shm_open 2 , 548269e767SBrooks Davis.Xr socket 2 558269e767SBrooks Davisor 568269e767SBrooks Davis.Xr socketpair 2 , 57d2893828SCismonXit is assigned all capability rights; for 58d2893828SCismonX.Xr accept 2 , 59d2893828SCismonX.Xr accept4 2 60d2893828SCismonXor 61d2893828SCismonX.Xr openat 2 , 62d2893828SCismonXit inherits capability rights from the "parent" file descriptor. 638269e767SBrooks DavisThose rights can be reduced (but never expanded) by using the 648269e767SBrooks Davis.Fn cap_rights_limit 658269e767SBrooks Davissystem call. 668269e767SBrooks DavisOnce capability rights are reduced, operations on the file descriptor will be 678269e767SBrooks Davislimited to those permitted by 688269e767SBrooks Davis.Fa rights . 698269e767SBrooks Davis.Pp 708269e767SBrooks DavisThe 718269e767SBrooks Davis.Fa rights 728269e767SBrooks Davisargument should be prepared using 738269e767SBrooks Davis.Xr cap_rights_init 3 748269e767SBrooks Davisfamily of functions. 758269e767SBrooks Davis.Pp 768269e767SBrooks DavisCapability rights assigned to a file descriptor can be obtained with the 778269e767SBrooks Davis.Xr cap_rights_get 3 788269e767SBrooks Davisfunction. 798269e767SBrooks Davis.Pp 808269e767SBrooks DavisThe complete list of the capability rights can be found in the 818269e767SBrooks Davis.Xr rights 4 828269e767SBrooks Davismanual page. 838269e767SBrooks Davis.Sh RETURN VALUES 848269e767SBrooks Davis.Rv -std 858269e767SBrooks Davis.Sh EXAMPLES 868269e767SBrooks DavisThe following example demonstrates how to limit file descriptor capability 878269e767SBrooks Davisrights to allow reading only. 888269e767SBrooks Davis.Bd -literal 898269e767SBrooks Daviscap_rights_t setrights; 908269e767SBrooks Davischar buf[1]; 918269e767SBrooks Davisint fd; 928269e767SBrooks Davis 938269e767SBrooks Davisfd = open("/tmp/foo", O_RDWR); 948269e767SBrooks Davisif (fd < 0) 958269e767SBrooks Davis err(1, "open() failed"); 968269e767SBrooks Davis 978269e767SBrooks Davisif (cap_enter() < 0) 988269e767SBrooks Davis err(1, "cap_enter() failed"); 998269e767SBrooks Davis 1008269e767SBrooks Daviscap_rights_init(&setrights, CAP_READ); 1018269e767SBrooks Davisif (cap_rights_limit(fd, &setrights) < 0) 1028269e767SBrooks Davis err(1, "cap_rights_limit() failed"); 1038269e767SBrooks Davis 1048269e767SBrooks Davisbuf[0] = 'X'; 1058269e767SBrooks Davis 1068269e767SBrooks Davisif (write(fd, buf, sizeof(buf)) > 0) 1078269e767SBrooks Davis errx(1, "write() succeeded!"); 1088269e767SBrooks Davis 1098269e767SBrooks Davisif (read(fd, buf, sizeof(buf)) < 0) 1108269e767SBrooks Davis err(1, "read() failed"); 1118269e767SBrooks Davis.Ed 1128269e767SBrooks Davis.Sh ERRORS 1138269e767SBrooks Davis.Fn cap_rights_limit 1148269e767SBrooks Davissucceeds unless: 1158269e767SBrooks Davis.Bl -tag -width Er 1168269e767SBrooks Davis.It Bq Er EBADF 1178269e767SBrooks DavisThe 1188269e767SBrooks Davis.Fa fd 1198269e767SBrooks Davisargument is not a valid active descriptor. 1208269e767SBrooks Davis.It Bq Er EINVAL 1218269e767SBrooks DavisAn invalid right has been requested in 1228269e767SBrooks Davis.Fa rights . 1238269e767SBrooks Davis.It Bq Er ENOSYS 1248269e767SBrooks DavisThe running kernel was compiled without 1258269e767SBrooks Davis.Cd "options CAPABILITY_MODE" . 1268269e767SBrooks Davis.It Bq Er ENOTCAPABLE 1278269e767SBrooks DavisThe 1288269e767SBrooks Davis.Fa rights 1298269e767SBrooks Davisargument contains capability rights not present for the given file descriptor. 1308269e767SBrooks DavisCapability rights list can only be reduced, never expanded. 1318269e767SBrooks Davis.El 1328269e767SBrooks Davis.Sh SEE ALSO 1338269e767SBrooks Davis.Xr accept 2 , 1348269e767SBrooks Davis.Xr accept4 2 , 1358269e767SBrooks Davis.Xr cap_enter 2 , 1368269e767SBrooks Davis.Xr fhopen 2 , 1378269e767SBrooks Davis.Xr kqueue 2 , 1388269e767SBrooks Davis.Xr mq_open 2 , 1398269e767SBrooks Davis.Xr open 2 , 1408269e767SBrooks Davis.Xr openat 2 , 1418269e767SBrooks Davis.Xr pdfork 2 , 1428269e767SBrooks Davis.Xr pipe 2 , 1438269e767SBrooks Davis.Xr read 2 , 1448269e767SBrooks Davis.Xr shm_open 2 , 1458269e767SBrooks Davis.Xr socket 2 , 1468269e767SBrooks Davis.Xr socketpair 2 , 1478269e767SBrooks Davis.Xr write 2 , 1488269e767SBrooks Davis.Xr cap_rights_get 3 , 1498269e767SBrooks Davis.Xr cap_rights_init 3 , 1508269e767SBrooks Davis.Xr err 3 , 1518269e767SBrooks Davis.Xr capsicum 4 , 1528269e767SBrooks Davis.Xr rights 4 1538269e767SBrooks Davis.Sh HISTORY 1548269e767SBrooks DavisThe 1558269e767SBrooks Davis.Fn cap_rights_limit 1568269e767SBrooks Davisfunction first appeared in 1578269e767SBrooks Davis.Fx 8.3 . 1588269e767SBrooks DavisSupport for capabilities and capabilities mode was developed as part of the 1598269e767SBrooks Davis.Tn TrustedBSD 1608269e767SBrooks DavisProject. 1618269e767SBrooks Davis.Sh AUTHORS 1628269e767SBrooks DavisThis function was created by 1638269e767SBrooks Davis.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 1648269e767SBrooks Davisunder sponsorship of the FreeBSD Foundation. 165