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.El 162.Sh EXAMPLES 163The following example first opens a capability to casper and then uses this 164capability to create the 165.Nm system.dns 166casper service and uses it to resolve an IP address. 167.Bd -literal 168cap_channel_t *capcas, *capdns; 169int familylimit, error; 170const char *ipstr = "127.0.0.1"; 171const char *typelimit = "ADDR2NAME"; 172char hname[NI_MAXHOST]; 173struct addrinfo hints, *res; 174 175/* Open capability to Casper. */ 176capcas = cap_init(); 177if (capcas == NULL) 178 err(1, "Unable to contact Casper"); 179 180/* Cache NLA for gai_strerror. */ 181caph_cache_catpages(); 182 183/* Enter capability mode sandbox. */ 184if (caph_enter() < 0) 185 err(1, "Unable to enter capability mode"); 186 187/* Use Casper capability to create capability to the system.dns service. */ 188capdns = cap_service_open(capcas, "system.dns"); 189if (capdns == NULL) 190 err(1, "Unable to open system.dns service"); 191 192/* Close Casper capability, we don't need it anymore. */ 193cap_close(capcas); 194 195/* Limit system.dns to reserve IPv4 addresses */ 196familylimit = AF_INET; 197if (cap_dns_family_limit(capdns, &familylimit, 1) < 0) 198 err(1, "Unable to limit access to the system.dns service"); 199 200/* Convert IP address in C-string to struct sockaddr. */ 201memset(&hints, 0, sizeof(hints)); 202hints.ai_family = familylimit; 203hints.ai_flags = AI_NUMERICHOST; 204error = cap_getaddrinfo(capdns, ipstr, NULL, &hints, &res); 205if (error != 0) 206 errx(1, "cap_getaddrinfo(): %s: %s", ipstr, gai_strerror(error)); 207 208/* Limit system.dns to reverse DNS lookups. */ 209if (cap_dns_type_limit(capdns, &typelimit, 1) < 0) 210 err(1, "Unable to limit access to the system.dns service"); 211 212/* Find hostname for the given IP address. */ 213error = cap_getnameinfo(capdns, res->ai_addr, res->ai_addrlen, hname, sizeof(hname), 214 NULL, 0, 0); 215if (error != 0) 216 errx(1, "cap_getnameinfo(): %s: %s", ipstr, gai_strerror(error)); 217 218printf("Name associated with %s is %s.\\n", ipstr, hname); 219.Ed 220.Sh SEE ALSO 221.Xr cap_enter 2 , 222.Xr caph_enter 3 , 223.Xr err 3 , 224.Xr gethostbyaddr 3 , 225.Xr gethostbyname 3 , 226.Xr gethostbyname2 3 , 227.Xr getnameinfo 3 , 228.Xr capsicum 4 , 229.Xr nv 9 230.Sh HISTORY 231The 232.Nm cap_dns 233service first appeared in 234.Fx 10.3 . 235.Sh AUTHORS 236The 237.Nm cap_dns 238service was implemented by 239.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 240under sponsorship from the FreeBSD Foundation. 241.Pp 242This manual page was written by 243.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . 244