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 March 18, 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 109.Xr nvlist 9 110for that function can contain the following values and types: 111.Bl -ohang -offset indent 112.It type ( NV_TYPE_STRING ) 113The 114.Va type 115can have two values: 116.Dv ADDR 117or 118.Dv NAME . 119The 120.Dv ADDR 121means that functions 122.Fn cap_gethostbyname , 123.Fn cap_gethostbyname2 124and 125.Fn cap_gethostbyaddr 126are allowed. 127In case when 128.Va type 129is set to 130.Dv NAME 131the 132.Fn cap_getnameinfo 133function is allowed. 134.It family ( NV_TYPE_NUMBER ) 135The 136.Va family 137limits service to one of the address families (e.g. 138.Dv AF_INET , AF_INET6 , 139etc.). 140.Sh EXAMPLES 141The following example first opens a capability to casper and then uses this 142capability to create the 143.Nm system.dns 144casper service and uses it to resolve an IP address. 145.Bd -literal 146cap_channel_t *capcas, *capdns; 147const char *typelimit = "ADDR"; 148int familylimit; 149const char *ipstr = "127.0.0.1"; 150struct in_addr ip; 151struct hostent *hp; 152 153/* Open capability to Casper. */ 154capcas = cap_init(); 155if (capcas == NULL) 156 err(1, "Unable to contact Casper"); 157 158/* Enter capability mode sandbox. */ 159if (cap_enter() < 0 && errno != ENOSYS) 160 err(1, "Unable to enter capability mode"); 161 162/* Use Casper capability to create capability to the system.dns service. */ 163capdns = cap_service_open(capcas, "system.dns"); 164if (capdns == NULL) 165 err(1, "Unable to open system.dns service"); 166 167/* Close Casper capability, we don't need it anymore. */ 168cap_close(capcas); 169 170/* Limit system.dns to reverse DNS lookups. */ 171if (cap_dns_type_limit(capdns, &typelimit, 1) < 0) 172 err(1, "Unable to limit access to the system.dns service"); 173 174/* Limit system.dns to reserve IPv4 addresses */ 175familylimit = AF_INET; 176if (cap_dns_family_limit(capdns, &familylimit, 1) < 0) 177 err(1, "Unable to limit access to the system.dns service"); 178 179/* Convert IP address in C-string to in_addr. */ 180if (!inet_aton(ipstr, &ip)) 181 errx(1, "Unable to parse IP address %s.", ipstr); 182 183/* Find hostname for the given IP address. */ 184hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET); 185if (hp == NULL) 186 errx(1, "No name associated with %s.", ipstr); 187 188printf("Name associated with %s is %s.\\n", ipstr, hp->h_name); 189.Ed 190.Sh SEE ALSO 191.Xr cap_enter 2 , 192.Xr err 3 , 193.Xr gethostbyaddr 3 , 194.Xr gethostbyname 3 , 195.Xr gethostbyname2 3 , 196.Xr getnameinfo 3 , 197.Xr capsicum 4 , 198.Xr nv 9 199.Sh AUTHORS 200The 201.Nm cap_dns 202service was implemented by 203.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 204under sponsorship from the FreeBSD Foundation. 205.Pp 206This manual page was written by 207.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 208