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 17, 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 nvlist.
 164 The exact format depends on the service the capability represents.
 165 .Pp
 166 The
 167 .Fn cap_send_nvlist
 168 function sends the given nvlist over the given capability.
 169 This is low level interface to communicate with casper services.
 170 Most services should provide higher level API.
 171 .Pp
 172 The
 173 .Fn cap_recv_nvlist
 174 function receives the given nvlist over the given capability.
 175 .Pp
 176 The
 177 .Fn cap_xfer_nvlist
 178 function sends the given nvlist, destroys it and receives new nvlist in
 179 response over the given capability.
 180 It does not matter if the function succeeds or fails, the nvlist given
 181 for sending will always be destroyed once the function returns.
 182 .Pp
 183 The
 184 .Fn cap_service_open
 185 function opens casper service of the given name through casper capability
 186 obtained via the
 187 .Fn cap_init
 188 function.
 189 The function returns capability that provides access to opened service.
 190 Casper supports the following services in the base system:
 191 .Bl -tag -width "system.random" -compact -offset indent
 192 .Pp
 193 .It system.dns
 194 provides DNS libc compatible API
 195 .It system.grp
 196 provides
 197 .Xr getgrent 3
 198 compatible API
 199 .It system.pwd
 200 provides
 201 .Xr getpwent 3
 202 compatible API
 203 .It system.random
 204 allows to obtain entropy from
 205 .Pa /dev/random
 206 .It system.sysctl
 207 provides
 208 .Xr sysctlbyname 3
 209 compatible API
 210 .It system.syslog
 211 provides
 212 .Xr syslog 3
 213 compatible API
 214 .Sh RETURN VALUES
 215 The
 216 .Fn cap_clone ,
 217 .Fn cap_init ,
 218 .Fn cap_recv_nvlist ,
 219 .Fn cap_service_open ,
 220 .Fn cap_wrap
 221 and
 222 .Fn cap_xfer_nvlist
 223 functions return
 224 .Dv NULL
 225 and set the
 226 .Va errno
 227 variable on failure.
 228 .Pp
 229 The
 230 .Fn cap_limit_get ,
 231 .Fn cap_limit_set
 232 and
 233 .Fn cap_send_nvlist
 234 functions return
 235 .Dv -1
 236 and set the
 237 .Va errno
 238 variable on failure.
 239 .Pp
 240 The
 241 .Fn cap_close ,
 242 .Fn cap_sock
 243 and
 244 .Fn cap_unwrap
 245 functions always succeed.
 246 .Sh EXAMPLES
 247 The following example first opens capability to the casper then using this
 248 capability creates new capability to the
 249 .Nm system.dns
 250 casper service and uses the latter capability to resolve IP address.
 251 .Bd -literal
 252 cap_channel_t *capcas, *capdns;
 253 nvlist_t *limits;
 254 const char *ipstr = "127.0.0.1";
 255 struct in_addr ip;
 256 struct hostent *hp;
 257
 258 /* Open capability to the Casper. */
 259 capcas = cap_init();
 260 if (capcas == NULL)
 261         err(1, "Unable to contact Casper");
 262
 263 /* Enter capability mode sandbox. */
 264 if (cap_enter() < 0 && errno != ENOSYS)
 265         err(1, "Unable to enter capability mode");
 266
 267 /* Use Casper capability to create capability to the system.dns service. */
 268 capdns = cap_service_open(capcas, "system.dns");
 269 if (capdns == NULL)
 270         err(1, "Unable to open system.dns service");
 271
 272 /* Close Casper capability, we don't need it anymore. */
 273 cap_close(capcas);
 274
 275 /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
 276 limits = nvlist_create(0);
 277 nvlist_add_string(limits, "type", "ADDR");
 278 nvlist_add_number(limits, "family", (uint64_t)AF_INET);
 279 if (cap_limit_set(capdns, limits) < 0)
 280         err(1, "Unable to limit access to the system.dns service");
 281
 282 /* Convert IP address in C-string to in_addr. */
 283 if (!inet_aton(ipstr, &ip))
 284         errx(1, "Unable to parse IP address %s.", ipstr);
 285
 286 /* Find hostname for the given IP address. */
 287 hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
 288 if (hp == NULL)
 289         errx(1, "No name associated with %s.", ipstr);
 290
 291 printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
 292 .Ed
 293 .Sh SEE ALSO
 294 .Xr cap_enter 2 ,
 295 .Xr execve 2 ,
 296 .Xr kevent 2 ,
 297 .Xr poll 2 ,
 298 .Xr select 2 ,
 299 .Xr cap_gethostbyaddr 3 ,
 300 .Xr err 3 ,
 301 .Xr gethostbyaddr 3 ,
 302 .Xr inet_aton 3 ,
 303 .Xr nv 3 ,
 304 .Xr capsicum 4 ,
 305 .Xr unix 4
 306 .Sh AUTHORS
 307 The
 308 .Nm libcasper
 309 library was implemented by
 310 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 311 under sponsorship from the FreeBSD Foundation.
 312 The
 313 .Nm libcasper
 314 new architecture was implemented by
 315 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 316 .