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