lib/libcasper/libcasper/libcasper.3

   1 .\" Copyright (c) 2013 The FreeBSD Foundation
   2 .\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 6, 2018
  32 .Dt LIBCASPER 3
  33 .Os
  34 .Sh NAME
  35 .Nm cap_init ,
  36 .Nm cap_wrap ,
  37 .Nm cap_unwrap ,
  38 .Nm cap_sock ,
  39 .Nm cap_clone ,
  40 .Nm cap_close ,
  41 .Nm cap_limit_get ,
  42 .Nm cap_limit_set ,
  43 .Nm cap_send_nvlist ,
  44 .Nm cap_recv_nvlist ,
  45 .Nm cap_xfer_nvlist ,
  46 .Nm cap_service_open
  47 .Nd "library for handling application capabilities"
  48 .Sh LIBRARY
  49 .Lb libcasper
  50 .Sh SYNOPSIS
  51 .Fd #define WITH_CASPER
  52 .In sys/nv.h
  53 .In libcasper.h
  54 .Ft "cap_channel_t *"
  55 .Fn cap_init "void"
  56 .Ft "cap_channel_t *"
  57 .Fn cap_wrap "int sock" "int flags"
  58 .Ft "int"
  59 .Fn cap_unwrap "cap_channel_t *chan" "int *flags"
  60 .Ft "int"
  61 .Fn cap_sock "const cap_channel_t *chan"
  62 .Ft "cap_channel_t *"
  63 .Fn cap_clone "const cap_channel_t *chan"
  64 .Ft "void"
  65 .Fn cap_close "cap_channel_t *chan"
  66 .Ft "int"
  67 .Fn cap_limit_get "const cap_channel_t *chan" "nvlist_t **limitsp"
  68 .Ft "int"
  69 .Fn cap_limit_set "const cap_channel_t *chan" "nvlist_t *limits"
  70 .Ft "int"
  71 .Fn cap_send_nvlist "const cap_channel_t *chan" "const nvlist_t *nvl"
  72 .Ft "nvlist_t *"
  73 .Fn cap_recv_nvlist "const cap_channel_t *chan"
  74 .Ft "nvlist_t *"
  75 .Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl"
  76 .Ft "cap_channel_t *"
  77 .Fn cap_service_open "const cap_channel_t *chan" "const char *name"
  78 .Sh DESCRIPTION
  79 The
  80 .Nm libcasper
  81 library allows to manage application capabilities through the casper process.
  82 .Pp
  83 The application capability (represented by the
  84 .Vt cap_channel_t
  85 type) is a communication channel between the caller and the casper process
  86 daemon or an instance of one of its services.
  87 A capability to the casper process obtained with the
  88 .Fn cap_init
  89 function allows to create capabilities to casper's services via the
  90 .Fn cap_service_open
  91 function.
  92 .Pp
  93 The
  94 .Fn cap_init
  95 function opens capability to the casper process.
  96 .Pp
  97 The
  98 .Fn cap_wrap
  99 function creates
 100 .Vt cap_channel_t
 101 based on the given socket.
 102 The function is used when capability is inherited through
 103 .Xr execve 2
 104 or send over
 105 .Xr unix 4
 106 domain socket as a regular file descriptor and has to be represented as
 107 .Vt cap_channel_t
 108 again.
 109 The
 110 .Fa flags
 111 argument defines the channel behavior.
 112 The supported flags are:
 113 .Bl -ohang -offset indent
 114 .It CASPER_NO_UNIQ
 115 The communication between process and casper uses no unique version of nvlist.
 116 .El
 117 .Pp
 118 The
 119 .Fn cap_unwrap
 120 function is the opposite of the
 121 .Fn cap_wrap
 122 function.
 123 It frees the
 124 .Vt cap_channel_t
 125 structure and returns
 126 .Xr unix 4
 127 domain socket associated with it.
 128 .Pp
 129 The
 130 .Fn cap_clone
 131 function clones the given capability.
 132 .Pp
 133 The
 134 .Fn cap_close
 135 function closes the given capability.
 136 .Pp
 137 The
 138 .Fn cap_sock
 139 function returns
 140 .Xr unix 4
 141 domain socket descriptor associated with the given capability for use with
 142 system calls like
 143 .Xr kevent 2 ,
 144 .Xr poll 2
 145 and
 146 .Xr select 2 .
 147 .Pp
 148 The
 149 .Fn cap_limit_get
 150 function stores current limits of the given capability in the
 151 .Fa limitsp
 152 argument.
 153 If the function return
 154 .Va 0
 155 and
 156 .Dv NULL
 157 is stored in
 158 .Fa limitsp
 159 it means there are no limits set.
 160 .Pp
 161 The
 162 .Fn cap_limit_set
 163 function sets limits for the given capability.
 164 The limits are provided as
 165 .Xr nvlist 9 .
 166 The exact format depends on the service the capability represents.
 167 .Pp
 168 The
 169 .Fn cap_send_nvlist
 170 function sends the given
 171 .Xr nvlist 9
 172 over the given capability.
 173 This is low level interface to communicate with casper services.
 174 Most services should provide higher level API.
 175 .Pp
 176 The
 177 .Fn cap_recv_nvlist
 178 function receives the given
 179 .Xr nvlist 9
 180 over the given capability.
 181 .Pp
 182 The
 183 .Fn cap_xfer_nvlist
 184 function sends the given
 185 .Xr nvlist 9 ,
 186 destroys it and receives new
 187 .Xr nvlist 9
 188 in response over the given capability.
 189 It does not matter if the function succeeds or fails, the
 190 .Xr nvlist 9
 191 given for sending will always be destroyed once the function returns.
 192 .Pp
 193 The
 194 .Fn cap_service_open
 195 function opens casper service of the given name through casper capability
 196 obtained via the
 197 .Fn cap_init
 198 function.
 199 The function returns capability that provides access to opened service.
 200 Casper supports the following services in the base system:
 201 .Bl -tag -width "system.random" -compact -offset indent
 202 .Pp
 203 .It system.dns
 204 provides DNS libc compatible API
 205 .It system.grp
 206 provides
 207 .Xr getgrent 3
 208 compatible API
 209 .It system.pwd
 210 provides
 211 .Xr getpwent 3
 212 compatible API
 213 .It system.random
 214 allows to obtain entropy from
 215 .Pa /dev/random
 216 .It system.sysctl
 217 provides
 218 .Xr sysctlbyname 3
 219 compatible API
 220 .It system.syslog
 221 provides
 222 .Xr syslog 3
 223 compatible API
 224 .Sh RETURN VALUES
 225 The
 226 .Fn cap_clone ,
 227 .Fn cap_init ,
 228 .Fn cap_recv_nvlist ,
 229 .Fn cap_service_open ,
 230 .Fn cap_wrap
 231 and
 232 .Fn cap_xfer_nvlist
 233 functions return
 234 .Dv NULL
 235 and set the
 236 .Va errno
 237 variable on failure.
 238 .Pp
 239 The
 240 .Fn cap_limit_get ,
 241 .Fn cap_limit_set
 242 and
 243 .Fn cap_send_nvlist
 244 functions return
 245 .Dv -1
 246 and set the
 247 .Va errno
 248 variable on failure.
 249 .Pp
 250 The
 251 .Fn cap_close ,
 252 .Fn cap_sock
 253 and
 254 .Fn cap_unwrap
 255 functions always succeed.
 256 .Sh SEE ALSO
 257 .Xr errno 2 ,
 258 .Xr execve 2 ,
 259 .Xr kevent 2 ,
 260 .Xr poll 2 ,
 261 .Xr select 2 ,
 262 .Xr cap_dns 3 ,
 263 .Xr cap_grp 3 ,
 264 .Xr cap_pwd 3 ,
 265 .Xr cap_ranodm 3 ,
 266 .Xr cap_sysctl 3 ,
 267 .Xr cap_syslog 3 ,
 268 .Xr capsicum 4 ,
 269 .Xr unix 4 ,
 270 .Xr nv 9
 271 .Sh AUTHORS
 272 The
 273 .Nm libcasper
 274 library was implemented by
 275 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 276 under sponsorship from the FreeBSD Foundation.
 277 The
 278 .Nm libcasper
 279 new architecture was implemented by
 280 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
 281 .