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