lib/libcasper/libcasper/libcasper.3

   1 .\" Copyright (c) 2013 The FreeBSD Foundation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd February 26, 2018
  31 .Dt LIBCASPER 3
  32 .Os
  33 .Sh NAME
  34 .Nm cap_init ,
  35 .Nm cap_wrap ,
  36 .Nm cap_unwrap ,
  37 .Nm cap_sock ,
  38 .Nm cap_clone ,
  39 .Nm cap_close ,
  40 .Nm cap_limit_get ,
  41 .Nm cap_limit_set ,
  42 .Nm cap_send_nvlist ,
  43 .Nm cap_recv_nvlist ,
  44 .Nm cap_xfer_nvlist ,
  45 .Nm cap_service_open
  46 .Nd "library for handling application capabilities"
  47 .Sh LIBRARY
  48 .Lb libcasper
  49 .Sh SYNOPSIS
  50 .Fd #define WITH_CASPER
  51 .In sys/nv.h
  52 .In libcasper.h
  53 .Ft "cap_channel_t *"
  54 .Fn cap_init "void"
  55 .Ft "cap_channel_t *"
  56 .Fn cap_wrap "int sock" "int flags"
  57 .Ft "int"
  58 .Fn cap_unwrap "cap_channel_t *chan" "int *flags"
  59 .Ft "int"
  60 .Fn cap_sock "const cap_channel_t *chan"
  61 .Ft "cap_channel_t *"
  62 .Fn cap_clone "const cap_channel_t *chan"
  63 .Ft "void"
  64 .Fn cap_close "cap_channel_t *chan"
  65 .Ft "int"
  66 .Fn cap_limit_get "const cap_channel_t *chan" "nvlist_t **limitsp"
  67 .Ft "int"
  68 .Fn cap_limit_set "const cap_channel_t *chan" "nvlist_t *limits"
  69 .Ft "int"
  70 .Fn cap_send_nvlist "const cap_channel_t *chan" "const nvlist_t *nvl"
  71 .Ft "nvlist_t *"
  72 .Fn cap_recv_nvlist "const cap_channel_t *chan"
  73 .Ft "nvlist_t *"
  74 .Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl"
  75 .Ft "cap_channel_t *"
  76 .Fn cap_service_open "const cap_channel_t *chan" "const char *name"
  77 .Sh DESCRIPTION
  78 The
  79 .Nm libcasper
  80 library allows to manage application capabilities through the casper process.
  81 .Pp
  82 The application capability (represented by the
  83 .Vt cap_channel_t
  84 type) is a communication channel between the caller and the casper process
  85 daemon or an instance of one of its services.
  86 A capability to the casper process obtained with the
  87 .Fn cap_init
  88 function allows to create capabilities to casper's services via the
  89 .Fn cap_service_open
  90 function.
  91 .Pp
  92 The
  93 .Fn cap_init
  94 function opens capability to the casper process.
  95 .Pp
  96 The
  97 .Fn cap_wrap
  98 function creates
  99 .Vt cap_channel_t
 100 based on the given socket.
 101 The function is used when capability is inherited through
 102 .Xr execve 2
 103 or send over
 104 .Xr unix 4
 105 domain socket as a regular file descriptor and has to be represented as
 106 .Vt cap_channel_t
 107 again.
 108 The
 109 .Fa flags
 110 argument defines the channel behavior.
 111 The supported flags are:
 112 .Bl -ohang -offset indent
 113 .It CASPER_NO_UNIQ
 114 The communication between process and casper uses no unique version of nvlist.
 115 .El
 116 .Pp
 117 The
 118 .Fn cap_unwrap
 119 function is the opposite of the
 120 .Fn cap_wrap
 121 function.
 122 It frees the
 123 .Vt cap_channel_t
 124 structure and returns
 125 .Xr unix 4
 126 domain socket associated with it.
 127 .Pp
 128 The
 129 .Fn cap_clone
 130 function clones the given capability.
 131 .Pp
 132 The
 133 .Fn cap_close
 134 function closes the given capability.
 135 .Pp
 136 The
 137 .Fn cap_sock
 138 function returns
 139 .Xr unix 4
 140 domain socket descriptor associated with the given capability for use with
 141 system calls like
 142 .Xr kevent 2 ,
 143 .Xr poll 2
 144 and
 145 .Xr select 2 .
 146 .Pp
 147 The
 148 .Fn cap_limit_get
 149 function stores current limits of the given capability in the
 150 .Fa limitsp
 151 argument.
 152 If the function return
 153 .Va 0
 154 and
 155 .Dv NULL
 156 is stored in
 157 .Fa limitsp
 158 it means there are no limits set.
 159 .Pp
 160 The
 161 .Fn cap_limit_set
 162 function sets limits for the given capability.
 163 The limits are provided as
 164 .Xr nvlist 9 .
 165 The exact format depends on the service the capability represents.
 166 .Pp
 167 The
 168 .Fn cap_send_nvlist
 169 function sends the given
 170 .Xr nvlist 9
 171 over the given capability.
 172 This is low level interface to communicate with casper services.
 173 Most services should provide higher level API.
 174 .Pp
 175 The
 176 .Fn cap_recv_nvlist
 177 function receives the given
 178 .Xr nvlist 9
 179 over the given capability.
 180 .Pp
 181 The
 182 .Fn cap_xfer_nvlist
 183 function sends the given
 184 .Xr nvlist 9,
 185 destroys it and receives new
 186 .Xr nvlist 9
 187 in response over the given capability.
 188 It does not matter if the function succeeds or fails, the
 189 .Xr nvlist 9
 190 given for sending will always be destroyed once the function returns.
 191 .Pp
 192 The
 193 .Fn cap_service_open
 194 function opens casper service of the given name through casper capability
 195 obtained via the
 196 .Fn cap_init
 197 function.
 198 The function returns capability that provides access to opened service.
 199 Casper supports the following services in the base system:
 200 .Bl -tag -width "system.random" -compact -offset indent
 201 .Pp
 202 .It system.dns
 203 provides DNS libc compatible API
 204 .It system.grp
 205 provides
 206 .Xr getgrent 3
 207 compatible API
 208 .It system.pwd
 209 provides
 210 .Xr getpwent 3
 211 compatible API
 212 .It system.random
 213 allows to obtain entropy from
 214 .Pa /dev/random
 215 .It system.sysctl
 216 provides
 217 .Xr sysctlbyname 3
 218 compatible API
 219 .It system.syslog
 220 provides
 221 .Xr syslog 3
 222 compatible API
 223 .Sh RETURN VALUES
 224 The
 225 .Fn cap_clone ,
 226 .Fn cap_init ,
 227 .Fn cap_recv_nvlist ,
 228 .Fn cap_service_open ,
 229 .Fn cap_wrap
 230 and
 231 .Fn cap_xfer_nvlist
 232 functions return
 233 .Dv NULL
 234 and set the
 235 .Va errno
 236 variable on failure.
 237 .Pp
 238 The
 239 .Fn cap_limit_get ,
 240 .Fn cap_limit_set
 241 and
 242 .Fn cap_send_nvlist
 243 functions return
 244 .Dv -1
 245 and set the
 246 .Va errno
 247 variable on failure.
 248 .Pp
 249 The
 250 .Fn cap_close ,
 251 .Fn cap_sock
 252 and
 253 .Fn cap_unwrap
 254 functions always succeed.
 255 .Sh EXAMPLES
 256 The following example first opens capability to the casper then using this
 257 capability creates new capability to the
 258 .Nm system.dns
 259 casper service and uses the latter capability to resolve IP address.
 260 .Bd -literal
 261 cap_channel_t *capcas, *capdns;
 262 nvlist_t *limits;
 263 const char *ipstr = "127.0.0.1";
 264 struct in_addr ip;
 265 struct hostent *hp;
 266
 267 /* Open capability to the Casper. */
 268 capcas = cap_init();
 269 if (capcas == NULL)
 270         err(1, "Unable to contact Casper");
 271
 272 /* Enter capability mode sandbox. */
 273 if (cap_enter() < 0 && errno != ENOSYS)
 274         err(1, "Unable to enter capability mode");
 275
 276 /* Use Casper capability to create capability to the system.dns service. */
 277 capdns = cap_service_open(capcas, "system.dns");
 278 if (capdns == NULL)
 279         err(1, "Unable to open system.dns service");
 280
 281 /* Close Casper capability, we don't need it anymore. */
 282 cap_close(capcas);
 283
 284 /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
 285 limits = nvlist_create(0);
 286 nvlist_add_string(limits, "type", "ADDR");
 287 nvlist_add_number(limits, "family", (uint64_t)AF_INET);
 288 if (cap_limit_set(capdns, limits) < 0)
 289         err(1, "Unable to limit access to the system.dns service");
 290
 291 /* Convert IP address in C-string to in_addr. */
 292 if (!inet_aton(ipstr, &ip))
 293         errx(1, "Unable to parse IP address %s.", ipstr);
 294
 295 /* Find hostname for the given IP address. */
 296 hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
 297 if (hp == NULL)
 298         errx(1, "No name associated with %s.", ipstr);
 299
 300 printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
 301 .Ed
 302 .Sh SEE ALSO
 303 .Xr cap_enter 2 ,
 304 .Xr execve 2 ,
 305 .Xr kevent 2 ,
 306 .Xr poll 2 ,
 307 .Xr select 2 ,
 308 .Xr cap_gethostbyaddr 3 ,
 309 .Xr err 3 ,
 310 .Xr gethostbyaddr 3 ,
 311 .Xr inet_aton 3 ,
 312 .Xr capsicum 4 ,
 313 .Xr unix 4 ,
 314 .Xr nv 9
 315 .Sh AUTHORS
 316 The
 317 .Nm libcasper
 318 library was implemented by
 319 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 320 under sponsorship from the FreeBSD Foundation.
 321 The
 322 .Nm libcasper
 323 new architecture was implemented by
 324 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 325 .