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 February 25, 2016 31.Dt LIBCASPER 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 libcasper 49.Sh SYNOPSIS 50.In libcasper.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.Ft "cap_channel_t *" 75.Fn cap_service_open "const cap_channel_t *chan" "const char *name" 76.Sh DESCRIPTION 77The 78.Nm libcapsicum 79library allows to manage application capabilities through the casper process. 80.Pp 81The application capability (represented by the 82.Vt cap_channel_t 83type) is a communication channel between the caller and the casper process 84daemon or an instance of one of its services. 85A capability to the casper process obtained with the 86.Fn cap_init 87function allows to create capabilities to casper's services via the 88.Fn cap_service_open 89function. 90.Pp 91The 92.Fn cap_init 93function opens capability to the casper process. 94.Pp 95The 96.Fn cap_wrap 97function creates 98.Vt cap_channel_t 99based on the given socket. 100The function is used when capability is inherited through 101.Xr execve 2 102or send over 103.Xr unix 4 104domain socket as a regular file descriptor and has to be represented as 105.Vt cap_channel_t 106again. 107.Pp 108The 109.Fn cap_unwrap 110function is the opposite of the 111.Fn cap_wrap 112function. 113It frees the 114.Vt cap_channel_t 115structure and returns 116.Xr unix 4 117domain socket associated with it. 118.Pp 119The 120.Fn cap_clone 121function clones the given capability. 122.Pp 123The 124.Fn cap_close 125function closes the given capability. 126.Pp 127The 128.Fn cap_sock 129function returns 130.Xr unix 4 131domain socket descriptor associated with the given capability for use with 132system calls like 133.Xr kevent 2 , 134.Xr poll 2 135and 136.Xr select 2 . 137.Pp 138The 139.Fn cap_limit_get 140function stores current limits of the given capability in the 141.Fa limitsp 142argument. 143If the function return 144.Va 0 145and 146.Dv NULL 147is stored in 148.Fa limitsp 149it means there are no limits set. 150.Pp 151The 152.Fn cap_limit_set 153function sets limits for the given capability. 154The limits are provided as nvlist. 155The exact format depends on the service the capability represents. 156.Pp 157The 158.Fn cap_send_nvlist 159function sends the given nvlist over the given capability. 160This is low level interface to communicate with casper services. 161Most services should provide higher level API. 162.Pp 163The 164.Fn cap_recv_nvlist 165function receives the given nvlist over the given capability. 166The 167.Fa flags 168argument defines what type the top nvlist is expected to be. 169If the nvlist flags do not match the flags passed to 170.Fn cap_recv_nvlist , 171the nvlist will not be returned. 172.Pp 173The 174.Fn cap_xfer_nvlist 175function sends the given nvlist, destroys it and receives new nvlist in 176response over the given capability. 177The 178.Fa flags 179argument defines what type the top nvlist is expected to be. 180If the nvlist flags do not match the flags passed to 181.Fn cap_xfer_nvlist , 182the nvlist will not be returned. 183It does not matter if the function succeeds or fails, the nvlist given 184for sending will always be destroyed once the function returns. 185.Pp 186The 187.Fn cap_service_open 188function opens casper service of the given name through casper capability 189obtained via the 190.Fn cap_init 191function. 192The function returns capability that provides access to opened service. 193.Sh RETURN VALUES 194The 195.Fn cap_clone , 196.Fn cap_init , 197.Fn cap_recv_nvlist , 198.Fn cap_service_open , 199.Fn cap_wrap 200and 201.Fn cap_xfer_nvlist 202functions return 203.Dv NULL 204and set the 205.Va errno 206variable on failure. 207.Pp 208The 209.Fn cap_limit_get , 210.Fn cap_limit_set 211and 212.Fn cap_send_nvlist 213functions return 214.Dv -1 215and set the 216.Va errno 217variable on failure. 218.Pp 219The 220.Fn cap_close , 221.Fn cap_sock 222and 223.Fn cap_unwrap 224functions always succeed. 225.Sh EXAMPLES 226The following example first opens capability to the casper then using this 227capability creates new capability to the 228.Nm system.dns 229casper service and uses the latter capability to resolve IP address. 230.Bd -literal 231cap_channel_t *capcas, *capdns; 232nvlist_t *limits; 233const char *ipstr = "127.0.0.1"; 234struct in_addr ip; 235struct hostent *hp; 236 237/* Open capability to the Casper. */ 238capcas = cap_init(); 239if (capcas == NULL) 240 err(1, "Unable to contact Casper"); 241 242/* Enter capability mode sandbox. */ 243if (cap_enter() < 0 && errno != ENOSYS) 244 err(1, "Unable to enter capability mode"); 245 246/* Use Casper capability to create capability to the system.dns service. */ 247capdns = cap_service_open(capcas, "system.dns"); 248if (capdns == NULL) 249 err(1, "Unable to open system.dns service"); 250 251/* Close Casper capability, we don't need it anymore. */ 252cap_close(capcas); 253 254/* Limit system.dns to reverse DNS lookups and IPv4 addresses. */ 255limits = nvlist_create(0); 256nvlist_add_string(limits, "type", "ADDR"); 257nvlist_add_number(limits, "family", (uint64_t)AF_INET); 258if (cap_limit_set(capdns, limits) < 0) 259 err(1, "Unable to limit access to the system.dns service"); 260 261/* Convert IP address in C-string to in_addr. */ 262if (!inet_aton(ipstr, &ip)) 263 errx(1, "Unable to parse IP address %s.", ipstr); 264 265/* Find hostname for the given IP address. */ 266hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET); 267if (hp == NULL) 268 errx(1, "No name associated with %s.", ipstr); 269 270printf("Name associated with %s is %s.\\n", ipstr, hp->h_name); 271.Ed 272.Sh SEE ALSO 273.Xr cap_enter 2 , 274.Xr execve 2 , 275.Xr kevent 2 , 276.Xr poll 2 , 277.Xr select 2 , 278.Xr cap_gethostbyaddr 3 , 279.Xr err 3 , 280.Xr gethostbyaddr 3 , 281.Xr inet_aton 3 , 282.Xr nv 3 , 283.Xr capsicum 4 , 284.Xr unix 4 285.Sh AUTHORS 286The 287.Nm libcasper 288library was implemented by 289.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 290under sponsorship from the FreeBSD Foundation. 291The 292.Nm libcasper 293new architecture was implemented by 294.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org 295. 296