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