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 June 27, 2022
  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 .Rs
 217 .%A R. Gilligan
 218 .%A S. Thomson
 219 .%A J. Bound
 220 .%A J. McCann
 221 .%A W. Stevens
 222 .%T Basic Socket Interface Extensions for IPv6
 223 .%R RFC 3493
 224 .%D February 2003
 225 .Re
 226 .Rs
 227 .%A S. Deering
 228 .%A B. Haberman
 229 .%A T. Jinmei
 230 .%A E. Nordmark
 231 .%A B. Zill
 232 .%T "IPv6 Scoped Address Architecture"
 233 .%R RFC 4007
 234 .%D March 2005
 235 .Re
 236 .Rs
 237 .%A Craig Metz
 238 .%T Protocol Independence Using the Sockets API
 239 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 240 .%D June 2000
 241 .Re
 242 .Sh STANDARDS
 243 The
 244 .Fn getnameinfo
 245 function is defined by the
 246 .St -p1003.1-2004
 247 specification and documented in
 248 .Tn "RFC 3493" ,
 249 .Dq Basic Socket Interface Extensions for IPv6 .
 250 .Sh CAVEATS
 251 .Fn getnameinfo
 252 can return both numeric and FQDN forms of the address specified in
 253 .Fa sa .
 254 There is no return value that indicates whether the string returned in
 255 .Fa host
 256 is a result of binary to numeric-text translation (like
 257 .Xr inet_ntop 3 ) ,
 258 or is the result of a DNS reverse lookup.
 259 Because of this, malicious parties could set up a PTR record as follows:
 260 .Bd -literal -offset indent
 261 1.0.0.127.in-addr.arpa. IN PTR  10.1.1.1
 262 .Ed
 263 .Pp
 264 and trick the caller of
 265 .Fn getnameinfo
 266 into believing that
 267 .Fa sa
 268 is
 269 .Li 10.1.1.1
 270 when it is actually
 271 .Li 127.0.0.1 .
 272 .Pp
 273 To prevent such attacks, the use of
 274 .Dv NI_NAMEREQD
 275 is recommended when the result of
 276 .Fn getnameinfo
 277 is used
 278 for access control purposes:
 279 .Bd -literal -offset indent
 280 struct sockaddr *sa;
 281 socklen_t salen;
 282 char addr[NI_MAXHOST];
 283 struct addrinfo hints, *res;
 284 int error;
 285
 286 error = getnameinfo(sa, salen, addr, sizeof(addr),
 287     NULL, 0, NI_NAMEREQD);
 288 if (error == 0) {
 289         memset(&hints, 0, sizeof(hints));
 290         hints.ai_socktype = SOCK_DGRAM; /*dummy*/
 291         hints.ai_flags = AI_NUMERICHOST;
 292         if (getaddrinfo(addr, "0", &hints, &res) == 0) {
 293                 /* malicious PTR record */
 294                 freeaddrinfo(res);
 295                 printf("bogus PTR record\en");
 296                 return -1;
 297         }
 298         /* addr is FQDN as a result of PTR lookup */
 299 } else {
 300         /* addr is numeric string */
 301         error = getnameinfo(sa, salen, addr, sizeof(addr),
 302             NULL, 0, NI_NUMERICHOST);
 303 }
 304 .Ed
 305 .\".Pp
 306 .\".Ox
 307 .\"intentionally uses a different
 308 .\".Dv NI_MAXHOST
 309 .\"value from what
 310 .\".Tn "RFC 2553"
 311 .\"suggests, to avoid buffer length handling mistakes.