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