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 August 15, 2020 28.Dt CAP_DNS 3 29.Os 30.Sh NAME 31.Nm cap_getaddrinfo , 32.Nm cap_getnameinfo , 33.Nm cap_gethostbyname , 34.Nm cap_gethostbyname2 , 35.Nm cap_gethostbyaddr , 36.Nm cap_dns_type_limit , 37.Nm cap_dns_family_limit 38.Nd "library for getting network host entry in capability mode" 39.Sh LIBRARY 40.Lb libcap_dns 41.Sh SYNOPSIS 42.In sys/nv.h 43.In libcasper.h 44.In casper/cap_dns.h 45.Ft int 46.Fn cap_getaddrinfo "cap_channel_t *chan" "const char *hostname" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" 47.Ft int 48.Fn cap_getnameinfo "cap_channel_t *chan" "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" 49.Ft "struct hostent *" 50.Fn cap_gethostbyname "const cap_channel_t *chan" "const char *name" 51.Ft "struct hostent *" 52.Fn cap_gethostbyname2 "const cap_channel_t *chan" "const char *name" "int af" 53.Ft "struct hostent *" 54.Fn cap_gethostbyaddr "const cap_channel_t *chan" "const void *addr" "socklen_t len" "int af" 55.Ft "int" 56.Fn cap_dns_type_limit "cap_channel_t *chan" "const char * const *types" "size_t ntypes" 57.Ft "int" 58.Fn cap_dns_family_limit "const cap_channel_t *chan" "const int *families" "size_t nfamilies" 59.Sh DESCRIPTION 60.Bf -symbolic 61This service is obsolete and 62.Xr cap_net 3 63should be used instead. 64The 65.Fn cap_getaddrinfo , 66and 67.Fn cap_getnameinfo , 68functions are preferred over the 69.Fn cap_gethostbyname , 70.Fn cap_gethostbyname2 , 71and 72.Fn cap_gethostbyaddr 73functions. 74.Ef 75.Pp 76The functions 77.Fn cap_gethostbyname , 78.Fn cap_gethostbyname2 , 79.Fn cep_gethostbyaddr 80and 81.Fn cap_getnameinfo 82are respectively equivalent to 83.Xr gethostbyname 3 , 84.Xr gethostbyname2 3 , 85.Xr gethostbyaddr 3 86and 87.Xr getnameinfo 3 88except that the connection to the 89.Nm system.dns 90service needs to be provided. 91.Pp 92The 93.Fn cap_dns_type_limit 94function limits the functions allowed in the service. 95The 96.Fa types 97variable can be set to 98.Dv ADDR2NAME 99or 100.Dv NAME2ADDR . 101See the 102.Sx LIMITS 103section for more details. 104The 105.Fa ntpyes 106variable contains the number of 107.Fa types 108provided. 109.Pp 110The 111.Fn cap_dns_family_limit 112functions allows to limit address families. 113For details see 114.Sx LIMITS . 115The 116.Fa nfamilies 117variable contains the number of 118.Fa families 119provided. 120.Sh LIMITS 121The preferred way of setting limits is to use the 122.Fn cap_dns_type_limit 123and 124.Fn cap_dns_family_limit 125functions, but the limits of service can be set also using 126.Xr cap_limit_set 3 . 127The 128.Xr nvlist 9 129for that function can contain the following values and types: 130.Bl -ohang -offset indent 131.It type ( NV_TYPE_STRING ) 132The 133.Va type 134can have two values: 135.Dv ADDR2NAME 136or 137.Dv NAME2ADDR . 138The 139.Dv ADDR2NAME 140means that reverse DNS lookups are allowed with 141.Fn cap_getnameinfo 142and 143.Fn cap_gethostbyaddr 144functions. 145In case when 146.Va type 147is set to 148.Dv NAME2ADDR 149the name resolution is allowed with 150.Fn cap_getaddrinfo , 151.Fn cap_gethostbyname , 152and 153.Fn cap_gethostbyname2 154functions. 155.It family ( NV_TYPE_NUMBER ) 156The 157.Va family 158limits service to one of the address families (e.g. 159.Dv AF_INET , AF_INET6 , 160etc.). 161.Sh EXAMPLES 162The following example first opens a capability to casper and then uses this 163capability to create the 164.Nm system.dns 165casper service and uses it to resolve an IP address. 166.Bd -literal 167cap_channel_t *capcas, *capdns; 168int familylimit, error; 169const char *ipstr = "127.0.0.1"; 170const char *typelimit = "ADDR2NAME"; 171char hname[NI_MAXHOST]; 172struct addrinfo hints, *res; 173 174/* Open capability to Casper. */ 175capcas = cap_init(); 176if (capcas == NULL) 177 err(1, "Unable to contact Casper"); 178 179/* Cache NLA for gai_strerror. */ 180caph_cache_catpages(); 181 182/* Enter capability mode sandbox. */ 183if (caph_enter() < 0) 184 err(1, "Unable to enter capability mode"); 185 186/* Use Casper capability to create capability to the system.dns service. */ 187capdns = cap_service_open(capcas, "system.dns"); 188if (capdns == NULL) 189 err(1, "Unable to open system.dns service"); 190 191/* Close Casper capability, we don't need it anymore. */ 192cap_close(capcas); 193 194/* Limit system.dns to reserve IPv4 addresses */ 195familylimit = AF_INET; 196if (cap_dns_family_limit(capdns, &familylimit, 1) < 0) 197 err(1, "Unable to limit access to the system.dns service"); 198 199/* Convert IP address in C-string to struct sockaddr. */ 200memset(&hints, 0, sizeof(hints)); 201hints.ai_family = familylimit; 202hints.ai_flags = AI_NUMERICHOST; 203error = cap_getaddrinfo(capdns, ipstr, NULL, &hints, &res); 204if (error != 0) 205 errx(1, "cap_getaddrinfo(): %s: %s", ipstr, gai_strerror(error)); 206 207/* Limit system.dns to reverse DNS lookups. */ 208if (cap_dns_type_limit(capdns, &typelimit, 1) < 0) 209 err(1, "Unable to limit access to the system.dns service"); 210 211/* Find hostname for the given IP address. */ 212error = cap_getnameinfo(capdns, res->ai_addr, res->ai_addrlen, hname, sizeof(hname), 213 NULL, 0, 0); 214if (error != 0) 215 errx(1, "cap_getnameinfo(): %s: %s", ipstr, gai_strerror(error)); 216 217printf("Name associated with %s is %s.\\n", ipstr, hname); 218.Ed 219.Sh SEE ALSO 220.Xr cap_enter 2 , 221.Xr caph_enter 3 , 222.Xr err 3 , 223.Xr gethostbyaddr 3 , 224.Xr gethostbyname 3 , 225.Xr gethostbyname2 3 , 226.Xr getnameinfo 3 , 227.Xr capsicum 4 , 228.Xr nv 9 229.Sh HISTORY 230The 231.Nm cap_dns 232service first appeared in 233.Fx 10.3 . 234.Sh AUTHORS 235The 236.Nm cap_dns 237service was implemented by 238.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 239under sponsorship from the FreeBSD Foundation. 240.Pp 241This manual page was written by 242.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 243