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 April 14, 2014
  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"
  72 .Ft "nvlist_t *"
  73 .Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl"
  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 .Pp
 175 The
 176 .Fn cap_xfer_nvlist
 177 function sends the given nvlist, destroys it and receives new nvlist in
 178 response over the given capability.
 179 It does not matter if the function succeeds or fails, the nvlist given
 180 for sending will always be destroyed once the function returns.
 181 .Pp
 182 The
 183 .Fn cap_service_open
 184 function opens casper service of the given name through casper capability
 185 obtained via the
 186 .Fn cap_init
 187 function.
 188 The function returns capability that provides access to opened service.
 189 .Sh RETURN VALUES
 190 The
 191 .Fn cap_clone ,
 192 .Fn cap_init ,
 193 .Fn cap_recv_nvlist ,
 194 .Fn cap_service_open ,
 195 .Fn cap_wrap
 196 and
 197 .Fn cap_xfer_nvlist
 198 functions return
 199 .Dv NULL
 200 and set the
 201 .Va errno
 202 variable on failure.
 203 .Pp
 204 The
 205 .Fn cap_limit_get ,
 206 .Fn cap_limit_set
 207 and
 208 .Fn cap_send_nvlist
 209 functions return
 210 .Dv -1
 211 and set the
 212 .Va errno
 213 variable on failure.
 214 .Pp
 215 The
 216 .Fn cap_close ,
 217 .Fn cap_sock
 218 and
 219 .Fn cap_unwrap
 220 functions always succeed.
 221 .Sh EXAMPLES
 222 The following example first opens capability to the
 223 .Xr casperd 8
 224 daemon, then using this capability creates new capability to the
 225 .Nm system.dns
 226 casper service and uses the latter capability to resolve IP address.
 227 .Bd -literal
 228 cap_channel_t *capcas, *capdns;
 229 nvlist_t *limits;
 230 const char *ipstr = "127.0.0.1";
 231 struct in_addr ip;
 232 struct hostent *hp;
 233
 234 /* Open capability to the Casper daemon. */
 235 capcas = cap_init();
 236 if (capcas == NULL)
 237         err(1, "Unable to contact Casper daemon");
 238
 239 /* Enter capability mode sandbox. */
 240 if (cap_enter() < 0 && errno != ENOSYS)
 241         err(1, "Unable to enter capability mode");
 242
 243 /* Use Casper capability to create capability to the system.dns service. */
 244 capdns = cap_service_open(capcas, "system.dns");
 245 if (capdns == NULL)
 246         err(1, "Unable to open system.dns service");
 247
 248 /* Close Casper capability, we don't need it anymore. */
 249 cap_close(capcas);
 250
 251 /* Limit system.dns to reverse DNS lookups and IPv4 addresses. */
 252 limits = nvlist_create(0);
 253 nvlist_add_string(limits, "type", "ADDR");
 254 nvlist_add_number(limits, "family", (uint64_t)AF_INET);
 255 if (cap_limit_set(capdns, limits) < 0)
 256         err(1, "Unable to limit access to the system.dns service");
 257
 258 /* Convert IP address in C-string to in_addr. */
 259 if (!inet_aton(ipstr, &ip))
 260         errx(1, "Unable to parse IP address %s.", ipstr);
 261
 262 /* Find hostname for the given IP address. */
 263 hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
 264 if (hp == NULL)
 265         errx(1, "No name associated with %s.", ipstr);
 266
 267 printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
 268 .Ed
 269 .Sh SEE ALSO
 270 .Xr cap_enter 2 ,
 271 .Xr execve 2 ,
 272 .Xr kevent 2 ,
 273 .Xr poll 2 ,
 274 .Xr select 2 ,
 275 .Xr cap_gethostbyaddr 3 ,
 276 .Xr err 3 ,
 277 .Xr gethostbyaddr 3 ,
 278 .Xr inet_aton 3 ,
 279 .Xr nv 3 ,
 280 .Xr capsicum 4 ,
 281 .Xr unix 4 ,
 282 .Xr casperd 8
 283 .Sh AUTHORS
 284 The
 285 .Nm libcapsicum
 286 library was implemented by
 287 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 288 under sponsorship from the FreeBSD Foundation.