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 13, 2019
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" "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 AUTHORS
179The
180.Nm cap_sysctl
181service was implemented by
182.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
183under sponsorship from the FreeBSD Foundation.
184.Pp
185This manual page was written by
186.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org .
187