lib/libcasper/services/cap_dns/cap_dns.3

   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
  59 This service is obsolete and
  60 .Xr cap_net 3
  61 should be used instead.
  62 The
  63 .Fn cap_getaddrinfo ,
  64 and
  65 .Fn cap_getnameinfo ,
  66 functions are preferred over the
  67 .Fn cap_gethostbyname ,
  68 .Fn cap_gethostbyname2 ,
  69 and
  70 .Fn cap_gethostbyaddr
  71 functions.
  72 .Ef
  73 .Pp
  74 The functions
  75 .Fn cap_gethostbyname ,
  76 .Fn cap_gethostbyname2 ,
  77 .Fn cep_gethostbyaddr
  78 and
  79 .Fn cap_getnameinfo
  80 are respectively equivalent to
  81 .Xr gethostbyname 3 ,
  82 .Xr gethostbyname2 3 ,
  83 .Xr gethostbyaddr 3
  84 and
  85 .Xr getnameinfo 3
  86 except that the connection to the
  87 .Nm system.dns
  88 service needs to be provided.
  89 .Pp
  90 The
  91 .Fn cap_dns_type_limit
  92 function limits the functions allowed in the service.
  93 The
  94 .Fa types
  95 variable can be set to
  96 .Dv ADDR2NAME
  97 or
  98 .Dv NAME2ADDR .
  99 See the
 100 .Sx LIMITS
 101 section for more details.
 102 The
 103 .Fa ntpyes
 104 variable contains the number of
 105 .Fa types
 106 provided.
 107 .Pp
 108 The
 109 .Fn cap_dns_family_limit
 110 functions allows to limit address families.
 111 For details see
 112 .Sx LIMITS .
 113 The
 114 .Fa nfamilies
 115 variable contains the number of
 116 .Fa families
 117 provided.
 118 .Sh LIMITS
 119 The preferred way of setting limits is to use the
 120 .Fn cap_dns_type_limit
 121 and
 122 .Fn cap_dns_family_limit
 123 functions, but the limits of service can be set also using
 124 .Xr cap_limit_set 3 .
 125 The
 126 .Xr nvlist 9
 127 for that function can contain the following values and types:
 128 .Bl -ohang -offset indent
 129 .It type ( NV_TYPE_STRING )
 130 The
 131 .Va type
 132 can have two values:
 133 .Dv ADDR2NAME
 134 or
 135 .Dv NAME2ADDR .
 136 The
 137 .Dv ADDR2NAME
 138 means that reverse DNS lookups are allowed with
 139 .Fn cap_getnameinfo
 140 and
 141 .Fn cap_gethostbyaddr
 142 functions.
 143 In case when
 144 .Va type
 145 is set to
 146 .Dv NAME2ADDR
 147 the name resolution is allowed with
 148 .Fn cap_getaddrinfo ,
 149 .Fn cap_gethostbyname ,
 150 and
 151 .Fn cap_gethostbyname2
 152 functions.
 153 .It family ( NV_TYPE_NUMBER )
 154 The
 155 .Va family
 156 limits service to one of the address families (e.g.
 157 .Dv AF_INET , AF_INET6 ,
 158 etc.).
 159 .El
 160 .Sh EXAMPLES
 161 The following example first opens a capability to casper and then uses this
 162 capability to create the
 163 .Nm system.dns
 164 casper service and uses it to resolve an IP address.
 165 .Bd -literal
 166 cap_channel_t *capcas, *capdns;
 167 int familylimit, error;
 168 const char *ipstr = "127.0.0.1";
 169 const char *typelimit = "ADDR2NAME";
 170 char hname[NI_MAXHOST];
 171 struct addrinfo hints, *res;
 172
 173 /* Open capability to Casper. */
 174 capcas = cap_init();
 175 if (capcas == NULL)
 176         err(1, "Unable to contact Casper");
 177
 178 /* Cache NLA for gai_strerror. */
 179 caph_cache_catpages();
 180
 181 /* Enter capability mode sandbox. */
 182 if (caph_enter() < 0)
 183         err(1, "Unable to enter capability mode");
 184
 185 /* Use Casper capability to create capability to the system.dns service. */
 186 capdns = cap_service_open(capcas, "system.dns");
 187 if (capdns == NULL)
 188         err(1, "Unable to open system.dns service");
 189
 190 /* Close Casper capability, we don't need it anymore. */
 191 cap_close(capcas);
 192
 193 /* Limit system.dns to reserve IPv4 addresses */
 194 familylimit = AF_INET;
 195 if (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. */
 199 memset(&hints, 0, sizeof(hints));
 200 hints.ai_family = familylimit;
 201 hints.ai_flags = AI_NUMERICHOST;
 202 error = cap_getaddrinfo(capdns, ipstr, NULL, &hints, &res);
 203 if (error != 0)
 204        errx(1, "cap_getaddrinfo(): %s: %s", ipstr, gai_strerror(error));
 205
 206 /* Limit system.dns to reverse DNS lookups. */
 207 if (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. */
 211 error = cap_getnameinfo(capdns, res->ai_addr, res->ai_addrlen, hname, sizeof(hname),
 212     NULL, 0, 0);
 213 if (error != 0)
 214         errx(1, "cap_getnameinfo(): %s: %s", ipstr, gai_strerror(error));
 215
 216 printf("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
 229 The
 230 .Nm cap_dns
 231 service first appeared in
 232 .Fx 10.3 .
 233 .Sh AUTHORS
 234 The
 235 .Nm cap_dns
 236 service was implemented by
 237 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 238 under sponsorship from the FreeBSD Foundation.
 239 .Pp
 240 This manual page was written by
 241 .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org .