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 25, 2016
  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 libcasper.h
  51 .In nv.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 libcapsicum
  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 .Sh RETURN VALUES
 194 The
 195 .Fn cap_clone ,
 196 .Fn cap_init ,
 197 .Fn cap_recv_nvlist ,
 198 .Fn cap_service_open ,
 199 .Fn cap_wrap
 200 and
 201 .Fn cap_xfer_nvlist
 202 functions return
 203 .Dv NULL
 204 and set the
 205 .Va errno
 206 variable on failure.
 207 .Pp
 208 The
 209 .Fn cap_limit_get ,
 210 .Fn cap_limit_set
 211 and
 212 .Fn cap_send_nvlist
 213 functions return
 214 .Dv -1
 215 and set the
 216 .Va errno
 217 variable on failure.
 218 .Pp
 219 The
 220 .Fn cap_close ,
 221 .Fn cap_sock
 222 and
 223 .Fn cap_unwrap
 224 functions always succeed.
 225 .Sh EXAMPLES
 226 The following example first opens capability to the casper then using this
 227 capability creates new capability to the
 228 .Nm system.dns
 229 casper service and uses the latter capability to resolve IP address.
 230 .Bd -literal
 231 cap_channel_t *capcas, *capdns;
 232 nvlist_t *limits;
 233 const char *ipstr = "127.0.0.1";
 234 struct in_addr ip;
 235 struct hostent *hp;
 236
 237 /* Open capability to the Casper. */
 238 capcas = cap_init();
 239 if (capcas == NULL)
 240         err(1, "Unable to contact Casper");
 241
 242 /* Enter capability mode sandbox. */
 243 if (cap_enter() < 0 && errno != ENOSYS)
 244         err(1, "Unable to enter capability mode");
 245
 246 /* Use Casper capability to create capability to the system.dns service. */
 247 capdns = cap_service_open(capcas, "system.dns");
 248 if (capdns == NULL)
 249         err(1, "Unable to open system.dns service");
 250
 251 /* Close Casper capability, we don't need it anymore. */
 252 cap_close(capcas);
 253
 254 /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
 255 limits = nvlist_create(0);
 256 nvlist_add_string(limits, "type", "ADDR");
 257 nvlist_add_number(limits, "family", (uint64_t)AF_INET);
 258 if (cap_limit_set(capdns, limits) < 0)
 259         err(1, "Unable to limit access to the system.dns service");
 260
 261 /* Convert IP address in C-string to in_addr. */
 262 if (!inet_aton(ipstr, &ip))
 263         errx(1, "Unable to parse IP address %s.", ipstr);
 264
 265 /* Find hostname for the given IP address. */
 266 hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
 267 if (hp == NULL)
 268         errx(1, "No name associated with %s.", ipstr);
 269
 270 printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
 271 .Ed
 272 .Sh SEE ALSO
 273 .Xr cap_enter 2 ,
 274 .Xr execve 2 ,
 275 .Xr kevent 2 ,
 276 .Xr poll 2 ,
 277 .Xr select 2 ,
 278 .Xr cap_gethostbyaddr 3 ,
 279 .Xr err 3 ,
 280 .Xr gethostbyaddr 3 ,
 281 .Xr inet_aton 3 ,
 282 .Xr nv 3 ,
 283 .Xr capsicum 4 ,
 284 .Xr unix 4
 285 .Sh AUTHORS
 286 The
 287 .Nm libcasper
 288 library was implemented by
 289 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 290 under sponsorship from the FreeBSD Foundation.
 291 The
 292 .Nm libcasper
 293 new architecture was implemented by
 294 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 295 .