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 November 5, 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 a 165.Xr nvlist 9 . 166The exact format depends on the service the capability represents. 167.Fn cap_limit_set 168frees the limits regardless of whether the operation succeeds or fails. 169.Pp 170The 171.Fn cap_send_nvlist 172function sends the given 173.Xr nvlist 9 174over the given capability. 175This is low level interface to communicate with casper services. 176Most services should provide higher level API. 177.Pp 178The 179.Fn cap_recv_nvlist 180function receives the given 181.Xr nvlist 9 182over the given capability. 183.Pp 184The 185.Fn cap_xfer_nvlist 186function sends the given 187.Xr nvlist 9 , 188destroys it and receives new 189.Xr nvlist 9 190in response over the given capability. 191It does not matter if the function succeeds or fails, the 192.Xr nvlist 9 193given for sending will always be destroyed once the function returns. 194.Pp 195The 196.Fn cap_service_open 197function opens casper service of the given name through casper capability 198obtained via the 199.Fn cap_init 200function. 201The function returns capability that provides access to opened service. 202Casper supports the following services in the base system: 203.Bl -tag -width "system.random" -compact -offset indent 204.Pp 205.It system.dns 206provides DNS libc compatible API 207.It system.grp 208provides 209.Xr getgrent 3 210compatible API 211.It system.pwd 212provides 213.Xr getpwent 3 214compatible API 215.It system.random 216allows to obtain entropy from 217.Pa /dev/random 218.It system.sysctl 219provides 220.Xr sysctlbyname 3 221compatible API 222.It system.syslog 223provides 224.Xr syslog 3 225compatible API 226.Sh RETURN VALUES 227The 228.Fn cap_clone , 229.Fn cap_init , 230.Fn cap_recv_nvlist , 231.Fn cap_service_open , 232.Fn cap_wrap 233and 234.Fn cap_xfer_nvlist 235functions return 236.Dv NULL 237and set the 238.Va errno 239variable on failure. 240.Pp 241The 242.Fn cap_limit_get , 243.Fn cap_limit_set 244and 245.Fn cap_send_nvlist 246functions return 247.Dv -1 248and set the 249.Va errno 250variable on failure. 251.Pp 252The 253.Fn cap_close , 254.Fn cap_sock 255and 256.Fn cap_unwrap 257functions always succeed. 258.Sh SEE ALSO 259.Xr errno 2 , 260.Xr execve 2 , 261.Xr kevent 2 , 262.Xr poll 2 , 263.Xr select 2 , 264.Xr cap_dns 3 , 265.Xr cap_grp 3 , 266.Xr cap_pwd 3 , 267.Xr cap_random 3 , 268.Xr cap_sysctl 3 , 269.Xr cap_syslog 3 , 270.Xr libcasper_service 3 , 271.Xr capsicum 4 , 272.Xr unix 4 , 273.Xr nv 9 274.Sh AUTHORS 275The 276.Nm libcasper 277library was implemented by 278.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 279under sponsorship from the FreeBSD Foundation. 280The 281.Nm libcasper 282new architecture was implemented by 283.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org 284. 285