lib/libc/net/getnameinfo.3

   1 .\"     $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
   2 .\"     $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $
   3 .\"
   4 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   5 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .\" $FreeBSD$
  20 .\"
  21 .Dd July 28, 2016
  22 .Dt GETNAMEINFO 3
  23 .Os
  24 .Sh NAME
  25 .Nm getnameinfo
  26 .Nd socket address structure to hostname and service name
  27 .Sh SYNOPSIS
  28 .In sys/types.h
  29 .In sys/socket.h
  30 .In netdb.h
  31 .Ft int
  32 .Fo getnameinfo
  33 .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host"
  34 .Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags"
  35 .Fc
  36 .Sh DESCRIPTION
  37 The
  38 .Fn getnameinfo
  39 function is used to convert a
  40 .Li sockaddr
  41 structure to a pair of host name and service strings.
  42 It is a replacement for and provides more flexibility than the
  43 .Xr gethostbyaddr 3
  44 and
  45 .Xr getservbyport 3
  46 functions and is the converse of the
  47 .Xr getaddrinfo 3
  48 function.
  49 .Pp
  50 If a link-layer address or UNIX-domain address is passed to
  51 .Fn getnameinfo ,
  52 its ASCII representation will be stored in
  53 .Fa host .
  54 The string pointed to by
  55 .Fa serv
  56 will be set to the empty string if non-NULL;
  57 .Fa flags
  58 will always be ignored.
  59 For a link-layer address,
  60 this can be used as a replacement of the legacy
  61 .Xr link_ntoa 3
  62 function.
  63 .Pp
  64 The
  65 .Li sockaddr
  66 structure
  67 .Fa sa
  68 should point to either a
  69 .Li sockaddr_in ,
  70 .Li sockaddr_in6 ,
  71 .Li sockaddr_dl ,
  72 or
  73 .Li sockaddr_un
  74 structure
  75 .Po for IPv4 ,
  76 IPv6,
  77 link-layer,
  78 or UNIX-domain respectively
  79 .Pc
  80 that is
  81 .Fa salen
  82 bytes long.
  83 .Pp
  84 The host and service names associated with
  85 .Fa sa
  86 are stored in
  87 .Fa host
  88 and
  89 .Fa serv
  90 which have length parameters
  91 .Fa hostlen
  92 and
  93 .Fa servlen .
  94 The maximum value for
  95 .Fa hostlen
  96 is
  97 .Dv NI_MAXHOST
  98 and
  99 the maximum value for
 100 .Fa servlen
 101 is
 102 .Dv NI_MAXSERV ,
 103 as defined by
 104 .Aq Pa netdb.h .
 105 If a length parameter is zero, no string will be stored.
 106 Otherwise, enough space must be provided to store the
 107 host name or service string plus a byte for the NUL terminator.
 108 .Pp
 109 The
 110 .Fa flags
 111 argument is formed by
 112 .Tn OR Ns 'ing
 113 the following values:
 114 .Bl -tag -width "NI_NUMERICSCOPEXX"
 115 .It Dv NI_NOFQDN
 116 A fully qualified domain name is not required for local hosts.
 117 The local part of the fully qualified domain name is returned instead.
 118 .It Dv NI_NUMERICHOST
 119 Return the address in numeric form, as if calling
 120 .Xr inet_ntop 3 ,
 121 instead of a host name.
 122 .It Dv NI_NAMEREQD
 123 A name is required.
 124 If the host name cannot be found in DNS and this flag is set,
 125 a non-zero error code is returned.
 126 If the host name is not found and the flag is not set, the
 127 address is returned in numeric form.
 128 .It NI_NUMERICSERV
 129 The service name is returned as a digit string representing the port number.
 130 .It NI_NUMERICSCOPE
 131 The scope identifier is returned as a digit string.
 132 .It NI_DGRAM
 133 Specifies that the service being looked up is a datagram
 134 service, and causes
 135 .Xr getservbyport 3
 136 to be called with a second argument of
 137 .Dq udp
 138 instead of its default of
 139 .Dq tcp .
 140 This is required for the few ports (512\-514) that have different services
 141 for
 142 .Tn UDP
 143 and
 144 .Tn TCP .
 145 .El
 146 .Pp
 147 This implementation allows numeric IPv6 address notation with scope identifier,
 148 as documented in chapter 11 of RFC 4007.
 149 IPv6 link-local address will appear as a string like
 150 .Dq Li fe80::1%ne0 .
 151 Refer to
 152 .Xr getaddrinfo 3
 153 for more information.
 154 .Sh RETURN VALUES
 155 .Fn getnameinfo
 156 returns zero on success or one of the error codes listed in
 157 .Xr gai_strerror 3
 158 if an error occurs.
 159 .Sh EXAMPLES
 160 The following code tries to get a numeric host name, and service name,
 161 for a given socket address.
 162 Observe that there is no hardcoded reference to a particular address family.
 163 .Bd -literal -offset indent
 164 struct sockaddr *sa;    /* input */
 165 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 166
 167 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
 168     sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
 169         errx(1, "could not get numeric hostname");
 170         /* NOTREACHED */
 171 }
 172 printf("host=%s, serv=%s\en", hbuf, sbuf);
 173 .Ed
 174 .Pp
 175 The following version checks if the socket address has a reverse address mapping:
 176 .Bd -literal -offset indent
 177 struct sockaddr *sa;    /* input */
 178 char hbuf[NI_MAXHOST];
 179
 180 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
 181     NI_NAMEREQD)) {
 182         errx(1, "could not resolve hostname");
 183         /* NOTREACHED */
 184 }
 185 printf("host=%s\en", hbuf);
 186 .Ed
 187 .Sh SEE ALSO
 188 .Xr gai_strerror 3 ,
 189 .Xr getaddrinfo 3 ,
 190 .Xr gethostbyaddr 3 ,
 191 .Xr getservbyport 3 ,
 192 .Xr inet_ntop 3 ,
 193 .Xr link_ntoa 3 ,
 194 .Xr resolver 3 ,
 195 .Xr inet 4 ,
 196 .Xr inet6 4 ,
 197 .Xr unix 4 ,
 198 .Xr hosts 5 ,
 199 .Xr resolv.conf 5 ,
 200 .Xr services 5 ,
 201 .Xr hostname 7 ,
 202 .Xr named 8
 203 .Rs
 204 .%A R. Gilligan
 205 .%A S. Thomson
 206 .%A J. Bound
 207 .%A J. McCann
 208 .%A W. Stevens
 209 .%T Basic Socket Interface Extensions for IPv6
 210 .%R RFC 3493
 211 .%D February 2003
 212 .Re
 213 .Rs
 214 .%A S. Deering
 215 .%A B. Haberman
 216 .%A T. Jinmei
 217 .%A E. Nordmark
 218 .%A B. Zill
 219 .%T "IPv6 Scoped Address Architecture"
 220 .%R RFC 4007
 221 .%D March 2005
 222 .Re
 223 .Rs
 224 .%A Craig Metz
 225 .%T Protocol Independence Using the Sockets API
 226 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 227 .%D June 2000
 228 .Re
 229 .Sh STANDARDS
 230 The
 231 .Fn getnameinfo
 232 function is defined by the
 233 .St -p1003.1-2004
 234 specification and documented in
 235 .Tn "RFC 3493" ,
 236 .Dq Basic Socket Interface Extensions for IPv6 .
 237 .Sh CAVEATS
 238 .Fn getnameinfo
 239 can return both numeric and FQDN forms of the address specified in
 240 .Fa sa .
 241 There is no return value that indicates whether the string returned in
 242 .Fa host
 243 is a result of binary to numeric-text translation (like
 244 .Xr inet_ntop 3 ) ,
 245 or is the result of a DNS reverse lookup.
 246 Because of this, malicious parties could set up a PTR record as follows:
 247 .Bd -literal -offset indent
 248 1.0.0.127.in-addr.arpa. IN PTR  10.1.1.1
 249 .Ed
 250 .Pp
 251 and trick the caller of
 252 .Fn getnameinfo
 253 into believing that
 254 .Fa sa
 255 is
 256 .Li 10.1.1.1
 257 when it is actually
 258 .Li 127.0.0.1 .
 259 .Pp
 260 To prevent such attacks, the use of
 261 .Dv NI_NAMEREQD
 262 is recommended when the result of
 263 .Fn getnameinfo
 264 is used
 265 for access control purposes:
 266 .Bd -literal -offset indent
 267 struct sockaddr *sa;
 268 socklen_t salen;
 269 char addr[NI_MAXHOST];
 270 struct addrinfo hints, *res;
 271 int error;
 272
 273 error = getnameinfo(sa, salen, addr, sizeof(addr),
 274     NULL, 0, NI_NAMEREQD);
 275 if (error == 0) {
 276         memset(&hints, 0, sizeof(hints));
 277         hints.ai_socktype = SOCK_DGRAM; /*dummy*/
 278         hints.ai_flags = AI_NUMERICHOST;
 279         if (getaddrinfo(addr, "0", &hints, &res) == 0) {
 280                 /* malicious PTR record */
 281                 freeaddrinfo(res);
 282                 printf("bogus PTR record\en");
 283                 return -1;
 284         }
 285         /* addr is FQDN as a result of PTR lookup */
 286 } else {
 287         /* addr is numeric string */
 288         error = getnameinfo(sa, salen, addr, sizeof(addr),
 289             NULL, 0, NI_NUMERICHOST);
 290 }
 291 .Ed
 292 .\".Pp
 293 .\".Ox
 294 .\"intentionally uses a different
 295 .\".Dv NI_MAXHOST
 296 .\"value from what
 297 .\".Tn "RFC 2553"
 298 .\"suggests, to avoid buffer length handling mistakes.