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 January 3, 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 .In sys/nv.h
  51 .In libcasper.h
  52 .Ft "cap_channel_t *"
  53 .Fn cap_init "void"
  54 .Ft "cap_channel_t *"
  55 .Fn cap_wrap "int sock"
  56 .Ft "int"
  57 .Fn cap_unwrap "cap_channel_t *chan"
  58 .Ft "int"
  59 .Fn cap_sock "const cap_channel_t *chan"
  60 .Ft "cap_channel_t *"
  61 .Fn cap_clone "const cap_channel_t *chan"
  62 .Ft "void"
  63 .Fn cap_close "cap_channel_t *chan"
  64 .Ft "int"
  65 .Fn cap_limit_get "const cap_channel_t *chan" "nvlist_t **limitsp"
  66 .Ft "int"
  67 .Fn cap_limit_set "const cap_channel_t *chan" "nvlist_t *limits"
  68 .Ft "int"
  69 .Fn cap_send_nvlist "const cap_channel_t *chan" "const nvlist_t *nvl"
  70 .Ft "nvlist_t *"
  71 .Fn cap_recv_nvlist "const cap_channel_t *chan" "int flags"
  72 .Ft "nvlist_t *"
  73 .Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl" "int flags"
  74 .Ft "cap_channel_t *"
  75 .Fn cap_service_open "const cap_channel_t *chan" "const char *name"
  76 .Sh DESCRIPTION
  77 The
  78 .Nm libcasper
  79 library allows to manage application capabilities through the casper process.
  80 .Pp
  81 The application capability (represented by the
  82 .Vt cap_channel_t
  83 type) is a communication channel between the caller and the casper process
  84 daemon or an instance of one of its services.
  85 A capability to the casper process obtained with the
  86 .Fn cap_init
  87 function allows to create capabilities to casper's services via the
  88 .Fn cap_service_open
  89 function.
  90 .Pp
  91 The
  92 .Fn cap_init
  93 function opens capability to the casper process.
  94 .Pp
  95 The
  96 .Fn cap_wrap
  97 function creates
  98 .Vt cap_channel_t
  99 based on the given socket.
 100 The function is used when capability is inherited through
 101 .Xr execve 2
 102 or send over
 103 .Xr unix 4
 104 domain socket as a regular file descriptor and has to be represented as
 105 .Vt cap_channel_t
 106 again.
 107 .Pp
 108 The
 109 .Fn cap_unwrap
 110 function is the opposite of the
 111 .Fn cap_wrap
 112 function.
 113 It frees the
 114 .Vt cap_channel_t
 115 structure and returns
 116 .Xr unix 4
 117 domain socket associated with it.
 118 .Pp
 119 The
 120 .Fn cap_clone
 121 function clones the given capability.
 122 .Pp
 123 The
 124 .Fn cap_close
 125 function closes the given capability.
 126 .Pp
 127 The
 128 .Fn cap_sock
 129 function returns
 130 .Xr unix 4
 131 domain socket descriptor associated with the given capability for use with
 132 system calls like
 133 .Xr kevent 2 ,
 134 .Xr poll 2
 135 and
 136 .Xr select 2 .
 137 .Pp
 138 The
 139 .Fn cap_limit_get
 140 function stores current limits of the given capability in the
 141 .Fa limitsp
 142 argument.
 143 If the function return
 144 .Va 0
 145 and
 146 .Dv NULL
 147 is stored in
 148 .Fa limitsp
 149 it means there are no limits set.
 150 .Pp
 151 The
 152 .Fn cap_limit_set
 153 function sets limits for the given capability.
 154 The limits are provided as nvlist.
 155 The exact format depends on the service the capability represents.
 156 .Pp
 157 The
 158 .Fn cap_send_nvlist
 159 function sends the given nvlist over the given capability.
 160 This is low level interface to communicate with casper services.
 161 Most services should provide higher level API.
 162 .Pp
 163 The
 164 .Fn cap_recv_nvlist
 165 function receives the given nvlist over the given capability.
 166 The
 167 .Fa flags
 168 argument defines what type the top nvlist is expected to be.
 169 If the nvlist flags do not match the flags passed to
 170 .Fn cap_recv_nvlist ,
 171 the nvlist will not be returned.
 172 .Pp
 173 The
 174 .Fn cap_xfer_nvlist
 175 function sends the given nvlist, destroys it and receives new nvlist in
 176 response over the given capability.
 177 The
 178 .Fa flags
 179 argument defines what type the top nvlist is expected to be.
 180 If the nvlist flags do not match the flags passed to
 181 .Fn cap_xfer_nvlist ,
 182 the nvlist will not be returned.
 183 It does not matter if the function succeeds or fails, the nvlist given
 184 for sending will always be destroyed once the function returns.
 185 .Pp
 186 The
 187 .Fn cap_service_open
 188 function opens casper service of the given name through casper capability
 189 obtained via the
 190 .Fn cap_init
 191 function.
 192 The function returns capability that provides access to opened service.
 193 Casper supports the following services in the base system:
 194 .Bl -tag -width "system.random" -compact -offset indent
 195 .Pp
 196 .It system.dns
 197 provides DNS libc compatible API
 198 .It system.grp
 199 provides
 200 .Xr getgrent 3
 201 compatible API
 202 .It system.pwd
 203 provides
 204 .Xr getpwent 3
 205 compatible API
 206 .It system.random
 207 allows to obtain entropy from
 208 .Pa /dev/random
 209 .It system.sysctl
 210 provides
 211 .Xr sysctlbyname 3
 212 compatible API
 213 .It system.syslog
 214 provides
 215 .Xr syslog 3
 216 compatible API
 217 .Sh RETURN VALUES
 218 The
 219 .Fn cap_clone ,
 220 .Fn cap_init ,
 221 .Fn cap_recv_nvlist ,
 222 .Fn cap_service_open ,
 223 .Fn cap_wrap
 224 and
 225 .Fn cap_xfer_nvlist
 226 functions return
 227 .Dv NULL
 228 and set the
 229 .Va errno
 230 variable on failure.
 231 .Pp
 232 The
 233 .Fn cap_limit_get ,
 234 .Fn cap_limit_set
 235 and
 236 .Fn cap_send_nvlist
 237 functions return
 238 .Dv -1
 239 and set the
 240 .Va errno
 241 variable on failure.
 242 .Pp
 243 The
 244 .Fn cap_close ,
 245 .Fn cap_sock
 246 and
 247 .Fn cap_unwrap
 248 functions always succeed.
 249 .Sh EXAMPLES
 250 The following example first opens capability to the casper then using this
 251 capability creates new capability to the
 252 .Nm system.dns
 253 casper service and uses the latter capability to resolve IP address.
 254 .Bd -literal
 255 cap_channel_t *capcas, *capdns;
 256 nvlist_t *limits;
 257 const char *ipstr = "127.0.0.1";
 258 struct in_addr ip;
 259 struct hostent *hp;
 260
 261 /* Open capability to the Casper. */
 262 capcas = cap_init();
 263 if (capcas == NULL)
 264         err(1, "Unable to contact Casper");
 265
 266 /* Enter capability mode sandbox. */
 267 if (cap_enter() < 0 && errno != ENOSYS)
 268         err(1, "Unable to enter capability mode");
 269
 270 /* Use Casper capability to create capability to the system.dns service. */
 271 capdns = cap_service_open(capcas, "system.dns");
 272 if (capdns == NULL)
 273         err(1, "Unable to open system.dns service");
 274
 275 /* Close Casper capability, we don't need it anymore. */
 276 cap_close(capcas);
 277
 278 /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
 279 limits = nvlist_create(0);
 280 nvlist_add_string(limits, "type", "ADDR");
 281 nvlist_add_number(limits, "family", (uint64_t)AF_INET);
 282 if (cap_limit_set(capdns, limits) < 0)
 283         err(1, "Unable to limit access to the system.dns service");
 284
 285 /* Convert IP address in C-string to in_addr. */
 286 if (!inet_aton(ipstr, &ip))
 287         errx(1, "Unable to parse IP address %s.", ipstr);
 288
 289 /* Find hostname for the given IP address. */
 290 hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
 291 if (hp == NULL)
 292         errx(1, "No name associated with %s.", ipstr);
 293
 294 printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
 295 .Ed
 296 .Sh SEE ALSO
 297 .Xr cap_enter 2 ,
 298 .Xr execve 2 ,
 299 .Xr kevent 2 ,
 300 .Xr poll 2 ,
 301 .Xr select 2 ,
 302 .Xr cap_gethostbyaddr 3 ,
 303 .Xr err 3 ,
 304 .Xr gethostbyaddr 3 ,
 305 .Xr inet_aton 3 ,
 306 .Xr nv 3 ,
 307 .Xr capsicum 4 ,
 308 .Xr unix 4
 309 .Sh AUTHORS
 310 The
 311 .Nm libcasper
 312 library was implemented by
 313 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 314 under sponsorship from the FreeBSD Foundation.
 315 The
 316 .Nm libcasper
 317 new architecture was implemented by
 318 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 319 .