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