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.Dd December 1, 2022 26.Dt CAP_SYSCTL 3 27.Os 28.Sh NAME 29.Nm cap_sysctl 30.Nd "library for getting or setting system information in capability mode" 31.Sh LIBRARY 32.Lb libcap_sysctl 33.Sh SYNOPSIS 34.In libcasper.h 35.In casper/cap_sysctl.h 36.Ft int 37.Fn cap_sysctl "cap_channel_t *chan" "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" 38.Ft int 39.Fn cap_sysctlbyname "cap_channel_t *chan" "const char *name" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" 40.Ft int 41.Fn cap_sysctlnametomib "cap_channel_t *chan" "const char *name" "int *mibp" "size_t *sizep" 42.Ft cap_sysctl_limit_t * 43.Fn cap_sysctl_limit_init "cap_channel_t *chan" 44.Ft cap_sysctl_limit_t * 45.Fn cap_sysctl_limit_name "cap_sysctl_limit_t *limit" "const char *name" "int flags" 46.Ft cap_sysctl_limit_t * 47.Fn cap_sysctl_limit_mib "cap_sysctl_limit_t *limit" "const int *mibp" "u_int miblen" "int flags" 48.Ft int 49.Fn cap_sysctl_limit "cap_sysctl_limit_t *limit" 50.Sh DESCRIPTION 51The 52.Fn cap_sysctl , 53.Fn cap_sysctlbyname 54and 55.Fn cap_sysctlnametomib 56functions are equivalent to 57.Xr sysctl 3 , 58.Xr sysctlbyname 3 59and 60.Xr sysctlnametomib 3 , 61except that they are implemented by the 62.Ql system.sysctl 63.Xr libcasper 3 64service and require a corresponding 65.Xr libcasper 3 66capability. 67.Sh LIMITS 68By default, the 69.Nm 70capability provides unrestricted access to the sysctl namespace. 71Applications typically only require access to a small number of sysctl 72variables; the 73.Fn cap_sysctl_limit 74interface can be used to restrict the sysctls that can be accessed using 75the 76.Nm 77capability. 78.Fn cap_sysctl_limit_init 79returns an opaque limit handle used to store a list of permitted sysctls 80and access rights. 81Rights are encoded using the following flags: 82.Pp 83.Bd -literal -offset indent -compact 84CAP_SYSCTL_READ allow reads of the sysctl variable 85CAP_SYSCTL_WRITE allow writes of the sysctl variable 86CAP_SYSCTL_RDWR allow reads and writes of the sysctl variable 87CAP_RECURSIVE permit access to any child of the sysctl variable 88.Ed 89.Pp 90The 91.Fn cap_sysctl_limit_name 92function adds the sysctl identified by 93.Ar name 94to the limit list, and 95.Fn cap_sysctl_limit_mib 96function adds the sysctl identified by 97.Ar mibp 98to the limit list. 99The access rights for the sysctl are specified in the 100.Ar flags 101parameter; at least one of 102.Dv CAP_SYSCTL_READ , 103.Dv CAP_SYSCTL_WRITE 104and 105.Dv CAP_SYSCTL_RDWR 106must be specified. 107.Fn cap_sysctl_limit 108applies a set of sysctl limits to the capability, denying access to sysctl 109variables not belonging to the set. 110It consumes the limit handle. 111After either success or failure, the user must not access the handle again. 112.Pp 113Once a set of limits is applied, subsequent calls to 114.Fn cap_sysctl_limit 115will fail unless the new set is a subset of the current set. 116.Pp 117.Fn cap_sysctlnametomib 118will succeed so long as the named sysctl variable is present in the limit set, 119regardless of its access rights. 120When a sysctl variable name is added to a limit set, its MIB identifier is 121automatically added to the set. 122.Sh EXAMPLES 123The following example first opens a capability to casper, uses this 124capability to create the 125.Nm system.sysctl 126casper service, and then uses the 127.Nm 128capability to get the value of 129.Dv kern.trap_enotcap . 130.Bd -literal 131cap_channel_t *capcas, *capsysctl; 132const char *name = "kern.trap_enotcap"; 133void *limit; 134size_t size; 135bool value; 136 137/* Open capability to Casper. */ 138capcas = cap_init(); 139if (capcas == NULL) 140 err(1, "Unable to contact Casper"); 141 142/* Enter capability mode sandbox. */ 143if (cap_enter() < 0 && errno != ENOSYS) 144 err(1, "Unable to enter capability mode"); 145 146/* Use Casper capability to create capability to the system.sysctl service. */ 147capsysctl = cap_service_open(capcas, "system.sysctl"); 148if (capsysctl == NULL) 149 err(1, "Unable to open system.sysctl service"); 150 151/* Close Casper capability, we don't need it anymore. */ 152cap_close(capcas); 153 154/* Create limit for one MIB with read access only. */ 155limit = cap_sysctl_limit_init(capsysctl); 156(void)cap_sysctl_limit_name(limit, name, CAP_SYSCTL_READ); 157 158/* Limit system.sysctl. */ 159if (cap_sysctl_limit(limit) < 0) 160 err(1, "Unable to set limits"); 161 162/* Fetch value. */ 163size = sizeof(value); 164if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0) 165 err(1, "Unable to get value of sysctl"); 166 167printf("The value of %s is %d.\\n", name, value); 168 169cap_close(capsysctl); 170.Ed 171.Sh RETURN VALUES 172.Fn cap_sysctl_limit_init 173will return a new limit handle on success or 174.Dv NULL 175on failure, and set 176.Va errno . 177.Fn cap_sysctl_limit_mib 178and 179.Fn cap_sysctl_limit_name 180will return the modified limit handle on success or 181.Dv NULL 182on failure and set 183.Va errno . 184After failure, the caller must not access the limit handle again. 185.Fn cap_sysctl_limit 186will return 187.Dv -1 188on failure and set 189.Va errno . 190.Fn cap_sysctl , 191.Fn cap_sysctlbyname , 192and 193.Fn cap_sysctlnametomib 194have the same return values as their non-capability-mode equivalents as 195documented in 196.Xr sysctl 3 . 197.Sh SEE ALSO 198.Xr cap_enter 2 , 199.Xr err 3 , 200.Xr sysctl 3 , 201.Xr sysctlbyname 3 , 202.Xr sysctlnametomib 3 , 203.Xr capsicum 4 , 204.Xr nv 9 205.Sh HISTORY 206The 207.Nm cap_sysctl 208service first appeared in 209.Fx 10.3 . 210.Sh AUTHORS 211The 212.Nm cap_sysctl 213service was implemented by 214.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 215under sponsorship from the FreeBSD Foundation. 216.Pp 217This manual page was written by 218.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 219