1 files changed, 348 insertions, 0 deletions

diff --git a/src/lib/libc/net/getnameinfo.3 b/src/lib/libc/net/getnameinfo.3
new file mode 100644
index 0000000000..3b3a0fd290
--- /dev/null
+++ b/src/lib/libc/net/getnameinfo.3
@@ -0,0 +1,348 @@
+.\"     $OpenBSD: getnameinfo.3,v 1.27 2003/08/28 10:16:38 jmc Exp $
+.\"     $KAME: getnameinfo.3,v 1.20 2001/01/05 13:37:37 itojun Exp $
+.\"
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\"     The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
+.\"
+.Dd May 25, 1995
+.Dt GETNAMEINFO 3
+.Os
+.\"
+.Sh NAME
+.Nm getnameinfo
+.Nd address-to-nodename translation in protocol-independent manner
+.\"
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Fd #include <netdb.h>
+.Ft int
+.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
+"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
+.\"
+.Sh DESCRIPTION
+The
+.Fn getnameinfo
+function is defined for protocol-independent address-to-nodename translation.
+Its functionality is a reverse conversion of
+.Xr getaddrinfo 3 ,
+and implements similar functionality to
+.Xr gethostbyaddr 3
+and
+.Xr getservbyport 3
+in a more sophisticated manner.
+.Pp
+This function looks up an IP address and port number provided by the
+caller in the DNS and system-specific database, and returns text
+strings for both in buffers provided by the caller.
+The function indicates successful completion by a zero return value;
+a non-zero return value indicates failure.
+.Pp
+The first argument,
+.Fa sa ,
+points to either a
+.Li sockaddr_in
+structure (for IPv4) or a
+.Li sockaddr_in6
+structure (for IPv6) that holds the IP address and port number.
+The
+.Fa salen
+argument gives the length of the
+.Li sockaddr_in
+or
+.Li sockaddr_in6
+structure.
+.Pp
+The function returns the nodename associated with the IP address in
+the buffer pointed to by the
+.Fa host
+argument.
+The caller provides the size of this buffer via the
+.Fa hostlen
+argument.
+The service name associated with the port number is returned in the buffer
+pointed to by
+.Fa serv ,
+and the
+.Fa servlen
+argument gives the length of this buffer.
+The caller specifies not to return either string by providing a zero
+value for the
+.Fa hostlen
+or
+.Fa servlen
+arguments.
+Otherwise, the caller must provide buffers large enough to hold the
+nodename and the service name, including the terminating null characters.
+.Pp
+Unfortunately most systems do not provide constants that specify the
+maximum size of either a fully-qualified domain name or a service name.
+Therefore to aid the application in allocating buffers for these two
+returned strings the following constants are defined in
+.Aq Pa netdb.h :
+.Bd -literal -offset
+#define NI_MAXHOST    MAXHOSTNAMELEN
+#define NI_MAXSERV    32
+.Ed
+.Pp
+The first value is actually defined as the constant
+.Dv MAXDNAME
+in recent versions of BIND's
+.Aq Pa arpa/nameser.h
+header (older versions of BIND define this constant to be 256)
+and the second is a guess based on the services listed in the current
+Assigned Numbers RFC.
+.Pp
+The final argument is a
+.Fa flag
+that changes the default actions of this function.
+By default the fully-qualified domain name (FQDN) for the host is
+looked up in the DNS and returned.
+If the flag bit
+.Dv NI_NOFQDN
+is set, only the nodename portion of the FQDN is returned for local hosts.
+.Pp
+If the
+.Fa flag
+bit
+.Dv NI_NUMERICHOST
+is set, or if the host's name cannot be located in the DNS,
+the numeric form of the host's address is returned instead of its name
+.Po
+e.g., by calling
+.Fn inet_ntop
+instead of
+.Fn gethostbyaddr
+.Pc .
+If the
+.Fa flag
+bit
+.Dv NI_NAMEREQD
+is set, an error is returned if the host's name cannot be located in the DNS.
+.Pp
+If the flag bit
+.Dv NI_NUMERICSERV
+is set, the numeric form of the service address is returned
+.Pq e.g., its port number
+instead of its name.
+The two
+.Dv NI_NUMERICxxx
+flags are required to support the
+.Fl n
+flag that many commands provide.
+.Pp
+A fifth flag bit,
+.Dv NI_DGRAM ,
+specifies that the service is a datagram service, and causes
+.Fn getservbyport
+to be called with a second argument of
+.Qq udp
+instead of its default of
+.Qq tcp .
+This is required for the few ports (512-514)
+that have different services for UDP and TCP.
+.Pp
+These
+.Dv NI_xxx
+flags are defined in
+.Aq Pa netdb.h .
+.\"
+.Ss Extension for scoped IPv6 address
+The implementation allows experimental numeric IPv6 address notation with
+scope identifier.
+IPv6 link-local address will appear as a string like
+.Dq Li fe80::1%ne0 .
+Refer to
+.Xr getaddrinfo 3
+for the notation.
+.\"
+.Sh EXAMPLES
+The following code tries to get a numeric hostname, and service name,
+for given socket address.
+Observe that there is no hardcoded reference to a particular address family.
+.Bd -literal -offset indent
+struct sockaddr *sa;    /* input */
+char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
+
+if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
+    sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
+        errx(1, "could not get numeric hostname");
+        /*NOTREACHED*/
+}
+printf("host=%s, serv=%s\en", hbuf, sbuf);
+.Ed
+.Pp
+The following version checks if the socket address has reverse address mapping.
+.Bd -literal -offset indent
+struct sockaddr *sa;    /* input */
+char hbuf[NI_MAXHOST];
+
+if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
+    NI_NAMEREQD)) {
+        errx(1, "could not resolve hostname");
+        /*NOTREACHED*/
+}
+printf("host=%s\en", hbuf);
+.Ed
+.\"
+.Sh DIAGNOSTICS
+The function indicates successful completion by a zero return value;
+a non-zero return value indicates failure.
+Error codes are as below:
+.Bl -tag -width Er
+.It Dv EAI_AGAIN
+The name could not be resolved at this time.
+Future attempts may succeed.
+.It Dv EAI_BADFLAGS
+The flags had an invalid value.
+.It Dv EAI_FAIL
+A non-recoverable error occurred.
+.It Dv EAI_FAMILY
+The address family was not recognized or the address length was invalid
+for the specified family.
+.It Dv EAI_MEMORY
+There was a memory allocation failure.
+.It Dv EAI_NONAME
+The name does not resolve for the supplied parameters.
+.Dv NI_NAMEREQD
+is set and the host's name cannot be located,
+or both nodename and servname were null.
+.It Dv EAI_SYSTEM
+A system error occurred.
+The error code can be found in errno.
+.El
+.\"
+.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr gethostbyaddr 3 ,
+.Xr getservbyport 3 ,
+.Xr hosts 5 ,
+.Xr resolv.conf 5 ,
+.Xr services 5 ,
+.Xr hostname 7 ,
+.Xr named 8
+.Rs
+.%A R. Gilligan
+.%A S. Thomson
+.%A J. Bound
+.%A W. Stevens
+.%T Basic Socket Interface Extensions for IPv6
+.%R RFC 2553
+.%D March 1999
+.Re
+.Rs
+.%A Tatsuya Jinmei
+.%A Atsushi Onoe
+.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%R internet draft
+.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
+.%O work in progress material
+.Re
+.Rs
+.%A Craig Metz
+.%T Protocol Independence Using the Sockets API
+.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
+.%D June 2000
+.Re
+.\"
+.Sh STANDARDS
+The
+.Fn getnameinfo
+function is defined in IEEE POSIX 1003.1g draft specification,
+and documented in
+.Dq Basic Socket Interface Extensions for IPv6
+.Pq RFC 2553 .
+.\"
+.Sh HISTORY
+The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
+.\"
+.Sh CAVEATS
+.Fn getnameinfo
+returns both numeric and FQDN notation of the address specified in
+.Fa sa .
+There is no return value that indicates if the string returned in
+.Fa host
+is a result of binary to numeric-text translation (like
+.Xr inet_ntop 3 ) ,
+or the result of DNS reverse lookup.
+Therefore, malicious parties could set up a PTR record as below:
+.Bd -literal -offset indent
+1.0.0.127.in-addr.arpa. IN PTR  10.1.1.1
+.Ed
+.Pp
+and trick the caller of
+.Fn getnameinfo
+into believing that
+.Fa sa
+is
+.Li 10.1.1.1
+when it actually is
+.Li 127.0.0.1 .
+.Pp
+To prevent such attacks, the use of
+.Dv NI_NAMEREQD
+is recommended when you use the result of
+.Fn getnameinfo
+for access control purposes:
+.Bd -literal -offset indent
+struct sockaddr *sa;
+socklen_t salen;
+char addr[NI_MAXHOST];
+struct addrinfo hints, *res;
+int error;
+
+error = getnameinfo(sa, salen, addr, sizeof(addr),
+    NULL, 0, NI_NAMEREQD);
+if (error == 0) {
+        memset(&hints, 0, sizeof(hints));
+        hints.ai_socktype = SOCK_DGRAM; /*dummy*/
+        hints.ai_flags = AI_NUMERICHOST;
+        if (getaddrinfo(addr, "0", &hints, &res) == 0) {
+                /* malicious PTR record */
+                freeaddrinfo(res);
+                printf("bogus PTR record\\n");
+                return -1;
+        }
+        /* addr is FQDN as a result of PTR lookup */
+} else {
+        /* addr is numeric string */
+        error = getnameinfo(sa, salen, addr, sizeof(addr),
+            NULL, 0, NI_NUMERICHOST);
+}
+.Ed
+.\"
+.Sh BUGS
+The current implementation is not thread-safe.
+.Pp
+The text was shamelessly copied from RFC 2553.
+.Pp
+.Ox
+intentionally uses a different
+.Dv NI_MAXHOST
+value from what RFC 2553 suggests, to avoid buffer length handling mistakes.