1.\" Copyright (c) 2013 The FreeBSD Foundation 2.\" All rights reserved. 3.\" 4.\" This documentation was written by Pawel Jakub Dawidek under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd May 2, 2015 31.Dt LIBCAPSICUM 3 32.Os 33.Sh NAME 34.Nm cap_init , 35.Nm cap_wrap , 36.Nm cap_unwrap , 37.Nm cap_sock , 38.Nm cap_clone , 39.Nm cap_close , 40.Nm cap_limit_get , 41.Nm cap_limit_set , 42.Nm cap_send_nvlist , 43.Nm cap_recv_nvlist , 44.Nm cap_xfer_nvlist , 45.Nm cap_service_open 46.Nd "library for handling application capabilities" 47.Sh LIBRARY 48.Lb libcapsicum 49.Sh SYNOPSIS 50.In libcapsicum.h 51.In nv.h 52.Ft "cap_channel_t *" 53.Fn cap_init "void" 54.Ft "cap_channel_t *" 55.Fn cap_wrap "int sock" 56.Ft "int" 57.Fn cap_unwrap "cap_channel_t *chan" 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" "int flags" 72.Ft "nvlist_t *" 73.Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl" "int flags" 74.In libcapsicum_service.h 75.Ft "cap_channel_t *" 76.Fn cap_service_open "const cap_channel_t *chan" "const char *name" 77.Sh DESCRIPTION 78The 79.Nm libcapsicum 80library allows to manage application capabilities through the 81.Xr casperd 8 82daemon. 83.Pp 84The application capability (represented by the 85.Vt cap_channel_t 86type) is a communication channel between the caller and the 87.Xr casperd 8 88daemon or an instance of one of its services. 89A capability to the 90.Xr casperd 8 91daemon obtained with the 92.Fn cap_init 93function allows to create capabilities to casper's services via the 94.Fn cap_service_open 95function. 96.Pp 97The 98.Fn cap_init 99function opens capability to the 100.Xr casperd 8 101daemon. 102.Pp 103The 104.Fn cap_wrap 105function creates 106.Vt cap_channel_t 107based on the given socket. 108The function is used when capability is inherited through 109.Xr execve 2 110or send over 111.Xr unix 4 112domain socket as a regular file descriptor and has to be represented as 113.Vt cap_channel_t 114again. 115.Pp 116The 117.Fn cap_unwrap 118function is the opposite of the 119.Fn cap_wrap 120function. 121It frees the 122.Vt cap_channel_t 123structure and returns 124.Xr unix 4 125domain socket associated with it. 126.Pp 127The 128.Fn cap_clone 129function clones the given capability. 130.Pp 131The 132.Fn cap_close 133function closes the given capability. 134.Pp 135The 136.Fn cap_sock 137function returns 138.Xr unix 4 139domain socket descriptor associated with the given capability for use with 140system calls like 141.Xr kevent 2 , 142.Xr poll 2 143and 144.Xr select 2 . 145.Pp 146The 147.Fn cap_limit_get 148function stores current limits of the given capability in the 149.Fa limitsp 150argument. 151If the function return 152.Va 0 153and 154.Dv NULL 155is stored in 156.Fa limitsp 157it means there are no limits set. 158.Pp 159The 160.Fn cap_limit_set 161function sets limits for the given capability. 162The limits are provided as nvlist. 163The exact format depends on the service the capability represents. 164.Pp 165The 166.Fn cap_send_nvlist 167function sends the given nvlist over the given capability. 168This is low level interface to communicate with casper services. 169Most services should provide higher level API. 170.Pp 171The 172.Fn cap_recv_nvlist 173function receives the given nvlist over the given capability. 174The 175.Fa flags 176argument defines what type the top nvlist is expected to be. 177If the nvlist flags do not match the flags passed to 178.Fn cap_recv_nvlist , 179the nvlist will not be returned. 180.Pp 181The 182.Fn cap_xfer_nvlist 183function sends the given nvlist, destroys it and receives new nvlist in 184response over the given capability. 185The 186.Fa flags 187argument defines what type the top nvlist is expected to be. 188If the nvlist flags do not match the flags passed to 189.Fn cap_xfer_nvlist , 190the nvlist will not be returned. 191It does not matter if the function succeeds or fails, the nvlist given 192for sending will always be destroyed once the function returns. 193.Pp 194The 195.Fn cap_service_open 196function opens casper service of the given name through casper capability 197obtained via the 198.Fn cap_init 199function. 200The function returns capability that provides access to opened service. 201.Sh RETURN VALUES 202The 203.Fn cap_clone , 204.Fn cap_init , 205.Fn cap_recv_nvlist , 206.Fn cap_service_open , 207.Fn cap_wrap 208and 209.Fn cap_xfer_nvlist 210functions return 211.Dv NULL 212and set the 213.Va errno 214variable on failure. 215.Pp 216The 217.Fn cap_limit_get , 218.Fn cap_limit_set 219and 220.Fn cap_send_nvlist 221functions return 222.Dv -1 223and set the 224.Va errno 225variable on failure. 226.Pp 227The 228.Fn cap_close , 229.Fn cap_sock 230and 231.Fn cap_unwrap 232functions always succeed. 233.Sh EXAMPLES 234The following example first opens capability to the 235.Xr casperd 8 236daemon, then using this capability creates new capability to the 237.Nm system.dns 238casper service and uses the latter capability to resolve IP address. 239.Bd -literal 240cap_channel_t *capcas, *capdns; 241nvlist_t *limits; 242const char *ipstr = "127.0.0.1"; 243struct in_addr ip; 244struct hostent *hp; 245 246/* Open capability to the Casper daemon. */ 247capcas = cap_init(); 248if (capcas == NULL) 249 err(1, "Unable to contact Casper daemon"); 250 251/* Enter capability mode sandbox. */ 252if (cap_enter() < 0 && errno != ENOSYS) 253 err(1, "Unable to enter capability mode"); 254 255/* Use Casper capability to create capability to the system.dns service. */ 256capdns = cap_service_open(capcas, "system.dns"); 257if (capdns == NULL) 258 err(1, "Unable to open system.dns service"); 259 260/* Close Casper capability, we don't need it anymore. */ 261cap_close(capcas); 262 263/* Limit system.dns to reverse DNS lookups and IPv4 addresses. */ 264limits = nvlist_create(0); 265nvlist_add_string(limits, "type", "ADDR"); 266nvlist_add_number(limits, "family", (uint64_t)AF_INET); 267if (cap_limit_set(capdns, limits) < 0) 268 err(1, "Unable to limit access to the system.dns service"); 269 270/* Convert IP address in C-string to in_addr. */ 271if (!inet_aton(ipstr, &ip)) 272 errx(1, "Unable to parse IP address %s.", ipstr); 273 274/* Find hostname for the given IP address. */ 275hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET); 276if (hp == NULL) 277 errx(1, "No name associated with %s.", ipstr); 278 279printf("Name associated with %s is %s.\\n", ipstr, hp->h_name); 280.Ed 281.Sh SEE ALSO 282.Xr cap_enter 2 , 283.Xr execve 2 , 284.Xr kevent 2 , 285.Xr poll 2 , 286.Xr select 2 , 287.Xr cap_gethostbyaddr 3 , 288.Xr err 3 , 289.Xr gethostbyaddr 3 , 290.Xr inet_aton 3 , 291.Xr nv 3 , 292.Xr capsicum 4 , 293.Xr unix 4 , 294.Xr casperd 8 295.Sh AUTHORS 296The 297.Nm libcapsicum 298library was implemented by 299.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 300under sponsorship from the FreeBSD Foundation. 301