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