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 79The 80.Nm libcasper 81library allows to manage application capabilities through the casper process. 82.Pp 83The application capability (represented by the 84.Vt cap_channel_t 85type) is a communication channel between the caller and the casper process 86daemon or an instance of one of its services. 87A capability to the casper process obtained with the 88.Fn cap_init 89function allows to create capabilities to casper's services via the 90.Fn cap_service_open 91function. 92.Pp 93The 94.Fn cap_init 95function opens capability to the casper process. 96.Pp 97The 98.Fn cap_wrap 99function creates 100.Vt cap_channel_t 101based on the given socket. 102The function is used when capability is inherited through 103.Xr execve 2 104or send over 105.Xr unix 4 106domain socket as a regular file descriptor and has to be represented as 107.Vt cap_channel_t 108again. 109The 110.Fa flags 111argument defines the channel behavior. 112The supported flags are: 113.Bl -ohang -offset indent 114.It CASPER_NO_UNIQ 115The communication between process and casper uses no unique version of nvlist. 116.El 117.Pp 118The 119.Fn cap_unwrap 120function is the opposite of the 121.Fn cap_wrap 122function. 123It frees the 124.Vt cap_channel_t 125structure and returns 126.Xr unix 4 127domain socket associated with it. 128.Pp 129The 130.Fn cap_clone 131function clones the given capability. 132.Pp 133The 134.Fn cap_close 135function closes the given capability. 136.Pp 137The 138.Fn cap_sock 139function returns 140.Xr unix 4 141domain socket descriptor associated with the given capability for use with 142system calls like 143.Xr kevent 2 , 144.Xr poll 2 145and 146.Xr select 2 . 147.Pp 148The 149.Fn cap_limit_get 150function stores current limits of the given capability in the 151.Fa limitsp 152argument. 153If the function return 154.Va 0 155and 156.Dv NULL 157is stored in 158.Fa limitsp 159it means there are no limits set. 160.Pp 161The 162.Fn cap_limit_set 163function sets limits for the given capability. 164The limits are provided as 165.Xr nvlist 9 . 166The exact format depends on the service the capability represents. 167.Pp 168The 169.Fn cap_send_nvlist 170function sends the given 171.Xr nvlist 9 172over the given capability. 173This is low level interface to communicate with casper services. 174Most services should provide higher level API. 175.Pp 176The 177.Fn cap_recv_nvlist 178function receives the given 179.Xr nvlist 9 180over the given capability. 181.Pp 182The 183.Fn cap_xfer_nvlist 184function sends the given 185.Xr nvlist 9 , 186destroys it and receives new 187.Xr nvlist 9 188in response over the given capability. 189It does not matter if the function succeeds or fails, the 190.Xr nvlist 9 191given for sending will always be destroyed once the function returns. 192.Pp 193The 194.Fn cap_service_open 195function opens casper service of the given name through casper capability 196obtained via the 197.Fn cap_init 198function. 199The function returns capability that provides access to opened service. 200Casper supports the following services in the base system: 201.Bl -tag -width "system.random" -compact -offset indent 202.Pp 203.It system.dns 204provides DNS libc compatible API 205.It system.grp 206provides 207.Xr getgrent 3 208compatible API 209.It system.pwd 210provides 211.Xr getpwent 3 212compatible API 213.It system.random 214allows to obtain entropy from 215.Pa /dev/random 216.It system.sysctl 217provides 218.Xr sysctlbyname 3 219compatible API 220.It system.syslog 221provides 222.Xr syslog 3 223compatible API 224.Sh RETURN VALUES 225The 226.Fn cap_clone , 227.Fn cap_init , 228.Fn cap_recv_nvlist , 229.Fn cap_service_open , 230.Fn cap_wrap 231and 232.Fn cap_xfer_nvlist 233functions return 234.Dv NULL 235and set the 236.Va errno 237variable on failure. 238.Pp 239The 240.Fn cap_limit_get , 241.Fn cap_limit_set 242and 243.Fn cap_send_nvlist 244functions return 245.Dv -1 246and set the 247.Va errno 248variable on failure. 249.Pp 250The 251.Fn cap_close , 252.Fn cap_sock 253and 254.Fn cap_unwrap 255functions 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 libcasper_service 3 , 269.Xr capsicum 4 , 270.Xr unix 4 , 271.Xr nv 9 272.Sh AUTHORS 273The 274.Nm libcasper 275library was implemented by 276.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 277under sponsorship from the FreeBSD Foundation. 278The 279.Nm libcasper 280new architecture was implemented by 281.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org 282. 283