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