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 May 5, 2020 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 void * 45.Fn cap_sysctl_limit_init "cap_channel_t *chan" 46.Ft void * 47.Fn cap_sysctl_limit_name "void *limit" "const char *name" "int flags" 48.Ft void * 49.Fn cap_sysctl_limit_mib "void *limit" "const int *mibp" "u_int miblen" "int flags" 50.Ft int 51.Fn cap_sysctl_limit "void *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. 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; 134int value; 135size_t size; 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. */ 163if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0) 164 err(1, "Unable to get value of sysctl"); 165 166printf("The value of %s is %d.\\n", name, value); 167 168cap_close(capsysctl); 169.Ed 170.Sh SEE ALSO 171.Xr cap_enter 2 , 172.Xr err 3 , 173.Xr sysctl 3 , 174.Xr sysctlbyname 3 , 175.Xr sysctlnametomib 3 , 176.Xr capsicum 4 , 177.Xr nv 9 178.Sh HISTORY 179The 180.Nm cap_sysctl 181service first appeared in 182.Fx 10.3 . 183.Sh AUTHORS 184The 185.Nm cap_sysctl 186service was implemented by 187.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 188under sponsorship from the FreeBSD Foundation. 189.Pp 190This manual page was written by 191.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 192