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