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