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