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 March 18, 2018 28.Dt CAP_SYSCTL 3 29.Os 30.Sh NAME 31.Nm cap_sysctlbyname 32.Nd "library for getting or setting system information in capability mode" 33.Sh LIBRARY 34.Lb libcap_sysctl 35.Sh SYNOPSIS 36.In sys/nv.h 37.In libcasper.h 38.In casper/cap_sysctl.h 39.Ft int 40.Fn cap_sysctlbyname "cap_channel_t *chan" " const char *name" " void *oldp" " size_t *oldlenp" " const void *newp" " size_t newlen" 41.Sh DESCRIPTION 42The function 43.Fn cap_sysctlbyname 44is equivalent to 45.Xr sysctlbyname 3 46except that the connection to the 47.Nm system.sysctl 48service needs to be provided. 49.Sh LIMITS 50The service can be limited using 51.Xr cap_limit_set 3 52function. 53The 54.Xr nvlist 9 55for that function can contain the following values and types: 56.Bl -ohang -offset indent 57.It ( NV_TYPE_NUMBER ) 58The name of the element with type number will be treated as the limited sysctl. 59The value of the element will describe the access rights for given sysctl. 60There are four different rights 61.Dv CAP_SYSCTL_READ , 62.Dv CAP_SYSCTL_WRITE , 63.Dv CAP_SYSCTL_RDWR , 64and 65.Dv CAP_SYSCTL_RECURSIVE . 66The 67.Dv CAP_SYSCTL_READ 68flag allows to fetch the value of a given sysctl. 69The 70.Dv CAP_SYSCTL_WIRTE 71flag allows to override the value of a given sysctl. 72The 73.Dv CAP_SYSCTL_RDWR 74is combination of the 75.Dv CAP_SYSCTL_WIRTE 76and 77.Dv CAP_SYSCTL_READ 78and allows to read and write the value of a given sysctl. 79The 80.Dv CAP_SYSCTL_RECURSIVE 81allows access to all children of a given sysctl. 82This right must be combined with at least one other right. 83.Sh EXAMPLES 84The following example first opens a capability to casper and then uses this 85capability to create the 86.Nm system.sysctl 87casper service and uses it to get the value of 88.Dv kern.trap_enotcap . 89.Bd -literal 90cap_channel_t *capcas, *capsysctl; 91const char *name = "kern.trap_enotcap"; 92nvlist_t *limits; 93int value; 94size_t size; 95 96/* Open capability to Casper. */ 97capcas = cap_init(); 98if (capcas == NULL) 99 err(1, "Unable to contact Casper"); 100 101/* Enter capability mode sandbox. */ 102if (cap_enter() < 0 && errno != ENOSYS) 103 err(1, "Unable to enter capability mode"); 104 105/* Use Casper capability to create capability to the system.sysctl service. */ 106capsysctl = cap_service_open(capcas, "system.sysctl"); 107if (capsysctl == NULL) 108 err(1, "Unable to open system.sysctl service"); 109 110/* Close Casper capability, we don't need it anymore. */ 111cap_close(capcas); 112 113/* Create limit for one MIB with read access only. */ 114limits = nvlist_create(0); 115nvlist_add_number(limits, name, CAP_SYSCTL_READ); 116 117/* Limit system.sysctl. */ 118if (cap_limit_set(capsysctl, limits) < 0) 119 err(1, "Unable to set limits"); 120 121/* Fetch value. */ 122if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0) 123 err(1, "Unable to get value of sysctl"); 124 125printf("The value of %s is %d.\\n", name, value); 126 127cap_close(capsysctl); 128.Ed 129.Sh SEE ALSO 130.Xr cap_enter 2 , 131.Xr err 3 , 132.Xr sysctlbyname 3 , 133.Xr capsicum 4 , 134.Xr nv 9 135.Sh AUTHORS 136The 137.Nm cap_sysctl 138service was implemented by 139.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 140under sponsorship from the FreeBSD Foundation. 141.Pp 142This manual page was written by 143.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 144