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