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