1.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd January 10, 2018 28.Dt CAP_DNS 3 29.Os 30.Sh NAME 31.Nm cap_gethostbyname , 32.Nm cap_gethostbyname2 , 33.Nm cap_gethostbyaddr , 34.Nm cap_getnameinfo , 35.Nm cap_dns_type_limit , 36.Nm cap_dns_family_limit 37.Nd "library for getting network host entry in capability mode" 38.Sh LIBRARY 39.Lb libcap_dns 40.Sh SYNOPSIS 41.In sys/nv.h 42.In libcasper.h 43.In casper/cap_dns.h 44.Ft "struct hostent *" 45.Fn cap_gethostbyname "const cap_channel_t *chan" "const char *name" 46.Ft "struct hostent *" 47.Fn cap_gethostbyname2 "const cap_channel_t *chan" "const char *name" "int af" 48.Ft "struct hostent *" 49.Fn cap_gethostbyaddr "const cap_channel_t *chan" "const void *addr" "socklen_t len" "int af" 50.Ft "int" 51.Fn cap_getnameinfo "const cap_channel_t *chan" "const void *name" "int namelen" 52.Ft "int" 53.Fn cap_dns_type_limit "cap_channel_t *chan" "const char * const *types" "size_t ntypes" 54.Ft "int" 55.Fn cap_dns_family_limit "const cap_channel_t *chan" "const int *families" "size_t nfamilies" 56.Sh DESCRIPTION 57The functions 58.Fn cap_gethostbyname , 59.Fn cap_gethostbyname2 , 60.Fn cep_gethostbyaddr 61and 62.Fn cap_getnameinfo 63are respectively equivalent to 64.Xr gethostbyname 2 , 65.Xr gethostbyname2 2 , 66.Xr gethostbyaddr 2 67and 68.Xr getnameinfo 2 69except that the connection to the 70.Nm system.dns 71service needs to be provided. 72.Pp 73The 74.Fn cap_dns_type_limit 75function limits the functions allowed in the service. 76The 77.Fa types 78variable can be set to 79.Dv ADDR 80or 81.Dv NAME . 82See the 83.Sx LIMITS 84section for more details. 85The 86.Fa ntpyes 87variable contains the number of 88.Fa types 89provided. 90.Pp 91The 92.Fn cap_dns_family_limit 93functions allows to limit address families. 94For details see 95.Sx LIMITS . 96The 97.Fa nfamilies 98variable contains the number of 99.Fa families 100provided. 101.Sh LIMITS 102The preferred way of setting limits is to use the 103.Fn cap_dns_type_limit 104and 105.Fn cap_dns_family_limit 106functions, but the limits of service can be set also using 107.Xr cap_limit_set 3 . 108The nvlist for that function can contain the following values and types: 109.Bl -ohang -offset indent 110.It type ( NV_TYPE_STRING ) 111The 112.Va type 113can have two values: 114.Dv ADDR 115or 116.Dv NAME . 117The 118.Dv ADDR 119means that functions 120.Fn cap_gethostbyname , 121.Fn cap_gethostbyname2 122and 123.Fn cap_gethostbyaddr 124are allowed. 125In case when 126.Va type 127is set to 128.Dv NAME 129the 130.Fn cap_getnameinfo 131function is allowed. 132.It family ( NV_TYPE_NUMBER ) 133The 134.Va family 135limits service to one of the address families (e.g. 136.Dv AF_INET , AF_INET6 , 137etc.). 138.Sh EXAMPLES 139The following example first opens a capability to casper and then uses this 140capability to create the 141.Nm system.dns 142casper service and uses it to resolve an IP address. 143.Bd -literal 144cap_channel_t *capcas, *capdns; 145const char *typelimit = "ADDR"; 146int familylimit; 147const char *ipstr = "127.0.0.1"; 148struct in_addr ip; 149struct hostent *hp; 150 151/* Open capability to Casper. */ 152capcas = cap_init(); 153if (capcas == NULL) 154 err(1, "Unable to contact Casper"); 155 156/* Enter capability mode sandbox. */ 157if (cap_enter() < 0 && errno != ENOSYS) 158 err(1, "Unable to enter capability mode"); 159 160/* Use Casper capability to create capability to the system.dns service. */ 161capdns = cap_service_open(capcas, "system.dns"); 162if (capdns == NULL) 163 err(1, "Unable to open system.dns service"); 164 165/* Close Casper capability, we don't need it anymore. */ 166cap_close(capcas); 167 168/* Limit system.dns to reverse DNS lookups. */ 169if (cap_dns_type_limit(capdns, &typelimit, 1) < 0) 170 err(1, "Unable to limit access to the system.dns service"); 171 172/* Limit system.dns to reserve IPv4 addresses */ 173familylimit = AF_INET; 174if (cap_dns_family_limit(capdns, &familylimit, 1) < 0) 175 err(1, "Unable to limit access to the system.dns service"); 176 177/* Convert IP address in C-string to in_addr. */ 178if (!inet_aton(ipstr, &ip)) 179 errx(1, "Unable to parse IP address %s.", ipstr); 180 181/* Find hostname for the given IP address. */ 182hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET); 183if (hp == NULL) 184 errx(1, "No name associated with %s.", ipstr); 185 186printf("Name associated with %s is %s.\\n", ipstr, hp->h_name); 187.Ed 188.Sh SEE ALSO 189.Xr cap_enter 2 , 190.Xr err 3 , 191.Xr gethostbyaddr 3 , 192.Xr gethostbyname 3 , 193.Xr gethostbyname2 3 , 194.Xr getnameinfo 3, 195.Xr nv 3 , 196.Xr capsicum 4 197.Sh AUTHORS 198The 199.Nm cap_dns 200service was implemented by 201.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 202under sponsorship from the FreeBSD Foundation. 203.Pp 204This manual page was written by 205.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 206