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