1.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 1, 2022 28.Dt CAP_SYSCTL 3 29.Os 30.Sh NAME 31.Nm cap_sysctl 32.Nd "library for getting or setting system information in capability mode" 33.Sh LIBRARY 34.Lb libcap_sysctl 35.Sh SYNOPSIS 36.In libcasper.h 37.In casper/cap_sysctl.h 38.Ft int 39.Fn cap_sysctl "cap_channel_t *chan" "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" 40.Ft int 41.Fn cap_sysctlbyname "cap_channel_t *chan" "const char *name" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" 42.Ft int 43.Fn cap_sysctlnametomib "cap_channel_t *chan" "const char *name" "int *mibp" "size_t *sizep" 44.Ft cap_sysctl_limit_t * 45.Fn cap_sysctl_limit_init "cap_channel_t *chan" 46.Ft cap_sysctl_limit_t * 47.Fn cap_sysctl_limit_name "cap_sysctl_limit_t *limit" "const char *name" "int flags" 48.Ft cap_sysctl_limit_t * 49.Fn cap_sysctl_limit_mib "cap_sysctl_limit_t *limit" "const int *mibp" "u_int miblen" "int flags" 50.Ft int 51.Fn cap_sysctl_limit "cap_sysctl_limit_t *limit" 52.Sh DESCRIPTION 53The 54.Fn cap_sysctl , 55.Fn cap_sysctlbyname 56and 57.Fn cap_sysctlnametomib 58functions are equivalent to 59.Xr sysctl 3 , 60.Xr sysctlbyname 3 61and 62.Xr sysctlnametomib 3 , 63except that they are implemented by the 64.Ql system.sysctl 65.Xr libcasper 3 66service and require a corresponding 67.Xr libcasper 3 68capability. 69.Sh LIMITS 70By default, the 71.Nm 72capability provides unrestricted access to the sysctl namespace. 73Applications typically only require access to a small number of sysctl 74variables; the 75.Fn cap_sysctl_limit 76interface can be used to restrict the sysctls that can be accessed using 77the 78.Nm 79capability. 80.Fn cap_sysctl_limit_init 81returns an opaque limit handle used to store a list of permitted sysctls 82and access rights. 83Rights are encoded using the following flags: 84.Pp 85.Bd -literal -offset indent -compact 86CAP_SYSCTL_READ allow reads of the sysctl variable 87CAP_SYSCTL_WRITE allow writes of the sysctl variable 88CAP_SYSCTL_RDWR allow reads and writes of the sysctl variable 89CAP_RECURSIVE permit access to any child of the sysctl variable 90.Ed 91.Pp 92The 93.Fn cap_sysctl_limit_name 94function adds the sysctl identified by 95.Ar name 96to the limit list, and 97.Fn cap_sysctl_limit_mib 98function adds the sysctl identified by 99.Ar mibp 100to the limit list. 101The access rights for the sysctl are specified in the 102.Ar flags 103parameter; at least one of 104.Dv CAP_SYSCTL_READ , 105.Dv CAP_SYSCTL_WRITE 106and 107.Dv CAP_SYSCTL_RDWR 108must be specified. 109.Fn cap_sysctl_limit 110applies a set of sysctl limits to the capability, denying access to sysctl 111variables not belonging to the set. 112It consumes the limit handle. 113After either success or failure, the user must not access the handle again. 114.Pp 115Once a set of limits is applied, subsequent calls to 116.Fn cap_sysctl_limit 117will fail unless the new set is a subset of the current set. 118.Pp 119.Fn cap_sysctlnametomib 120will succeed so long as the named sysctl variable is present in the limit set, 121regardless of its access rights. 122When a sysctl variable name is added to a limit set, its MIB identifier is 123automatically added to the set. 124.Sh EXAMPLES 125The following example first opens a capability to casper, uses this 126capability to create the 127.Nm system.sysctl 128casper service, and then uses the 129.Nm 130capability to get the value of 131.Dv kern.trap_enotcap . 132.Bd -literal 133cap_channel_t *capcas, *capsysctl; 134const char *name = "kern.trap_enotcap"; 135void *limit; 136size_t size; 137bool value; 138 139/* Open capability to Casper. */ 140capcas = cap_init(); 141if (capcas == NULL) 142 err(1, "Unable to contact Casper"); 143 144/* Enter capability mode sandbox. */ 145if (cap_enter() < 0 && errno != ENOSYS) 146 err(1, "Unable to enter capability mode"); 147 148/* Use Casper capability to create capability to the system.sysctl service. */ 149capsysctl = cap_service_open(capcas, "system.sysctl"); 150if (capsysctl == NULL) 151 err(1, "Unable to open system.sysctl service"); 152 153/* Close Casper capability, we don't need it anymore. */ 154cap_close(capcas); 155 156/* Create limit for one MIB with read access only. */ 157limit = cap_sysctl_limit_init(capsysctl); 158(void)cap_sysctl_limit_name(limit, name, CAP_SYSCTL_READ); 159 160/* Limit system.sysctl. */ 161if (cap_sysctl_limit(limit) < 0) 162 err(1, "Unable to set limits"); 163 164/* Fetch value. */ 165size = sizeof(value); 166if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0) 167 err(1, "Unable to get value of sysctl"); 168 169printf("The value of %s is %d.\\n", name, value); 170 171cap_close(capsysctl); 172.Ed 173.Sh RETURN VALUES 174.Fn cap_sysctl_limit_init 175will return a new limit handle on success or 176.Dv NULL 177on failure, and set 178.Va errno . 179.Fn cap_sysctl_limit_mib 180and 181.Fn cap_sysctl_limit_name 182will return the modified limit handle on success or 183.Dv NULL 184on failure and set 185.Va errno . 186After failure, the caller must not access the limit handle again. 187.Fn cap_sysctl_limit 188will return 189.Dv -1 190on failure and set 191.Va errno . 192.Fn cap_sysctl , 193.Fn cap_sysctlbyname , 194and 195.Fn cap_sysctlnametomib 196have the same return values as their non-capability-mode equivalents as 197documented in 198.Xr sysctl 3 . 199.Sh SEE ALSO 200.Xr cap_enter 2 , 201.Xr err 3 , 202.Xr sysctl 3 , 203.Xr sysctlbyname 3 , 204.Xr sysctlnametomib 3 , 205.Xr capsicum 4 , 206.Xr nv 9 207.Sh HISTORY 208The 209.Nm cap_sysctl 210service first appeared in 211.Fx 10.3 . 212.Sh AUTHORS 213The 214.Nm cap_sysctl 215service was implemented by 216.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 217under sponsorship from the FreeBSD Foundation. 218.Pp 219This manual page was written by 220.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 221