lib/libcasper/services/cap_sysctl/cap_sysctl.3

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