lookup.subproj/getnameinfo.3

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