lib/libc/net/getnameinfo.3

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