|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.google.common.net.InetAddresses
@Beta public final class InetAddresses
Static utility methods pertaining to InetAddress
instances.
Important note: Unlike InetAddress.getByName()
, the
methods of this class never cause DNS services to be accessed. For
this reason, you should prefer these methods as much as possible over
their JDK equivalents whenever you are expecting to handle only
IP address string literals -- there is no blocking DNS penalty for a
malformed string.
This class hooks into the sun.net.util.IPAddressUtil
class
to make use of the textToNumericFormatV4
and
textToNumericFormatV6
methods directly as a means to avoid
accidentally traversing all nameservices (it can be vitally important
to avoid, say, blocking on DNS at times).
When dealing with Inet4Address
and Inet6Address
objects as byte arrays (vis. InetAddress.getAddress()
) they
are 4 and 16 bytes in length, respectively, and represent the address
in network byte order.
Examples of IP addresses and their byte representations:
"127.0.0.1"
.7f 00 00 01
"::1"
.00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01
2001:db8::/32
),
"2001:db8::1"
.20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01
"::192.168.0.1"
.00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01
"::ffff:192.168.0.1"
.00 00 00 00 00 00 00 00 00 00 ff ff c0 a8 00 01
A few notes about IPv6 "IPv4 mapped" addresses and their observed
use in Java.
"IPv4 mapped" addresses were originally a representation of IPv4
addresses for use on an IPv6 socket that could receive both IPv4
and IPv6 connections (by disabling the IPV6_V6ONLY
socket
option on an IPv6 socket). Yes, it's confusing. Nevertheless,
these "mapped" addresses were never supposed to be seen on the
wire. That assumption was dropped, some say mistakenly, in later
RFCs with the apparent aim of making IPv4-to-IPv6 transition simpler.
Technically one can create a 128bit IPv6 address with the wire
format of a "mapped" address, as shown above, and transmit it in an
IPv6 packet header. However, Java's InetAddress creation methods
appear to adhere doggedly to the original intent of the "mapped"
address: all "mapped" addresses return Inet4Address
objects.
For added safety, it is common for IPv6 network operators to filter
all packets where either the source or destination address appears to
be a "compat" or "mapped" address. Filtering suggestions usually
recommend discarding any packets with source or destination addresses
in the invalid range ::/3
, which includes both of these bizarre
address formats. For more information on "bogons", including lists
of IPv6 bogon space, see:
Nested Class Summary | |
---|---|
static class |
InetAddresses.TeredoInfo
A simple data class to encapsulate the information to be found in a Teredo address. |
Method Summary | |
---|---|
static int |
coerceToInteger(InetAddress ip)
Returns an integer representing an IPv4 address regardless of whether the supplied argument is an IPv4 address or not. |
static InetAddress |
forString(String ipString)
Returns the InetAddress having the given string
representation. |
static InetAddress |
forUriString(String hostAddr)
Returns an InetAddress representing the literal IPv4 or IPv6 host portion of a URL, encoded in the format specified by RFC 3986 section 3.2.2. |
static Inet4Address |
fromInteger(int address)
Returns an Inet4Address having the integer value specified by the argument. |
static InetAddress |
fromLittleEndianByteArray(byte[] addr)
Returns an address from a little-endian ordered byte array (the opposite of what InetAddress.getByAddress(java.lang.String, byte[]) expects). |
static Inet4Address |
get6to4IPv4Address(Inet6Address ip)
Returns the IPv4 address embedded in a 6to4 address. |
static Inet4Address |
getCoercedIPv4Address(InetAddress ip)
Coerces an IPv6 address into an IPv4 address. |
static Inet4Address |
getCompatIPv4Address(Inet6Address ip)
Returns the IPv4 address embedded in an IPv4 compatible address. |
static Inet4Address |
getEmbeddedIPv4ClientAddress(Inet6Address ip)
Examines the Inet6Address to extract the embedded IPv4 client address if the InetAddress is an IPv6 address of one of the specified address types that contain an embedded IPv4 address. |
static Inet4Address |
getIsatapIPv4Address(Inet6Address ip)
Returns the IPv4 address embedded in an ISATAP address. |
static InetAddresses.TeredoInfo |
getTeredoInfo(Inet6Address ip)
Returns the Teredo information embedded in a Teredo address. |
static boolean |
hasEmbeddedIPv4ClientAddress(Inet6Address ip)
Examines the Inet6Address to determine if it is an IPv6 address of one of the specified address types that contain an embedded IPv4 address. |
static boolean |
is6to4Address(Inet6Address ip)
Evaluates whether the argument is a 6to4 address. |
static boolean |
isCompatIPv4Address(Inet6Address ip)
Evaluates whether the argument is an IPv6 "compat" address. |
static boolean |
isInetAddress(String ipString)
Returns true if the supplied string is a valid IP string
literal, false otherwise. |
static boolean |
isIsatapAddress(Inet6Address ip)
Evaluates whether the argument is an ISATAP address. |
static boolean |
isTeredoAddress(Inet6Address ip)
Evaluates whether the argument is a Teredo address. |
static boolean |
isUriInetAddress(String ipString)
Returns true if the supplied string is a valid URI IP string
literal, false otherwise. |
static String |
toUriString(InetAddress ip)
Returns the string representation of an InetAddress suitable
for inclusion in a URI. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static InetAddress forString(String ipString)
InetAddress
having the given string
representation.
This deliberately avoids all nameservice lookups (e.g. no DNS).
ipString
- String
containing an IPv4 or IPv6 string literal,
e.g. "192.168.0.1"
or "2001:db8::1"
InetAddress
representing the argument
IllegalArgumentException
- if the argument is not a valid
IP string literalpublic static boolean isInetAddress(String ipString)
true
if the supplied string is a valid IP string
literal, false
otherwise.
ipString
- String
to evaluated as an IP string literal
true
if the argument is a valid IP string literalpublic static String toUriString(InetAddress ip)
InetAddress
suitable
for inclusion in a URI.
For IPv4 addresses, this is identical to
InetAddress.getHostAddress()
, but for IPv6 addresses it
surrounds this text with square brackets; for example
"[2001:db8::1]"
.
Per section 3.2.2 of
http://tools.ietf.org/html/rfc3986,
a URI containing an IPv6 string literal is of the form
"http://[2001:db8::1]:8888/index.html"
.
Use of either InetAddress.getHostAddress()
or this
method is recommended over InetAddress.toString()
when an
IP address string literal is desired. This is because
InetAddress.toString()
prints the hostname and the IP
address string joined by a "/".
ip
- InetAddress
to be converted to URI string literal
String
containing URI-safe string literalpublic static InetAddress forUriString(String hostAddr)
This function is similar to forString(String)
,
however, it requires that IPv6 addresses are surrounded by square brackets.
This function is the inverse of
toUriString(java.net.InetAddress)
.
hostAddr
- A RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address
hostAddr
IllegalArgumentException
- if hostAddr
is not a valid
IPv4 address, or IPv6 address surrounded by square bracketspublic static boolean isUriInetAddress(String ipString)
true
if the supplied string is a valid URI IP string
literal, false
otherwise.
ipString
- String
to evaluated as an IP URI host string literal
true
if the argument is a valid IP URI hostpublic static boolean isCompatIPv4Address(Inet6Address ip)
An "IPv4 compatible", or "compat", address is one with 96 leading
bits of zero, with the remaining 32 bits interpreted as an
IPv4 address. These are conventionally represented in string
literals as "::192.168.0.1"
, though "::c0a8:1"
is
also considered an IPv4 compatible address (and equivalent to
"::192.168.0.1"
).
For more on IPv4 compatible addresses see section 2.5.5.1 of http://tools.ietf.org/html/rfc4291
NOTE: This method is different from
Inet6Address.isIPv4CompatibleAddress()
in that it more
correctly classifies "::"
and "::1"
as
proper IPv6 addresses (which they are), NOT IPv4 compatible
addresses (which they are generally NOT considered to be).
ip
- Inet6Address
to be examined for embedded IPv4
compatible address format
true
if the argument is a valid "compat" addresspublic static Inet4Address getCompatIPv4Address(Inet6Address ip)
ip
- Inet6Address
to be examined for an embedded
IPv4 address
Inet4Address
of the embedded IPv4 address
IllegalArgumentException
- if the argument is not a valid
IPv4 compatible addresspublic static boolean is6to4Address(Inet6Address ip)
6to4 addresses begin with the "2002::/16"
prefix.
The next 32 bits are the IPv4 address of the host to which
IPv6-in-IPv4 tunneled packets should be routed.
For more on 6to4 addresses see section 2 of http://tools.ietf.org/html/rfc3056
ip
- Inet6Address
to be examined for 6to4 address
format
true
if the argument is a 6to4 addresspublic static Inet4Address get6to4IPv4Address(Inet6Address ip)
ip
- Inet6Address
to be examined for embedded IPv4
in 6to4 address.
Inet4Address
of embedded IPv4 in 6to4 address.
IllegalArgumentException
- if the argument is not a valid
IPv6 6to4 address.public static boolean isTeredoAddress(Inet6Address ip)
Teredo addresses begin with the "2001::/32"
prefix.
ip
- Inet6Address
to be examined for Teredo address
format.
true
if the argument is a Teredo addresspublic static InetAddresses.TeredoInfo getTeredoInfo(Inet6Address ip)
ip
- Inet6Address
to be examined for embedded Teredo
information
TeredoInfo
IllegalArgumentException
- if the argument is not a valid
IPv6 Teredo addresspublic static boolean isIsatapAddress(Inet6Address ip)
From RFC 5214: "ISATAP interface identifiers are constructed in Modified EUI-64 format [...] by concatenating the 24-bit IANA OUI (00-00-5E), the 8-bit hexadecimal value 0xFE, and a 32-bit IPv4 address in network byte order [...]"
For more on ISATAP addresses see section 6.1 of http://tools.ietf.org/html/rfc5214
ip
- Inet6Address
to be examined for ISATAP address
format.
true
if the argument is an ISATAP addresspublic static Inet4Address getIsatapIPv4Address(Inet6Address ip)
ip
- Inet6Address
to be examined for embedded IPv4
in ISATAP address
Inet4Address
of embedded IPv4 in an ISATAP address
IllegalArgumentException
- if the argument is not a valid
IPv6 ISATAP addresspublic static boolean hasEmbeddedIPv4ClientAddress(Inet6Address ip)
NOTE: ISATAP addresses are explicitly excluded from this method due to their trivial spoofability. With other transition addresses spoofing involves (at least) infection of one's BGP routing table.
ip
- Inet6Address
to be examined for embedded IPv4
client address.
true
if there is an embedded IPv4 client address.public static Inet4Address getEmbeddedIPv4ClientAddress(Inet6Address ip)
NOTE: ISATAP addresses are explicitly excluded from this method due to their trivial spoofability. With other transition addresses spoofing involves (at least) infection of one's BGP routing table.
ip
- Inet6Address
to be examined for embedded IPv4
client address.
Inet4Address
of embedded IPv4 client address.
IllegalArgumentException
- if the argument does not have a valid
embedded IPv4 address.public static Inet4Address getCoercedIPv4Address(InetAddress ip)
HACK: As long as applications continue to use IPv4 addresses for
indexing into tables, accounting, et cetera, it may be necessary to
coerce IPv6 addresses into IPv4 addresses. This function does
so by hashing the upper 64 bits into 224.0.0.0/3
(64 bits into 29 bits).
A "coerced" IPv4 address is equivalent to itself.
NOTE: This function is failsafe for security purposes: ALL IPv6 addresses (except localhost (::1)) are hashed to avoid the security risk associated with extracting an embedded IPv4 address that might permit elevated privileges.
ip
- InetAddress
to "coerce"
Inet4Address
represented "coerced" addresspublic static int coerceToInteger(InetAddress ip)
IPv6 addresses are coerced to IPv4 addresses before being converted to integers.
As long as there are applications that assume that all IP addresses are IPv4 addresses and can therefore be converted safely to integers (for whatever purpose) this function can be used to handle IPv6 addresses as well until the application is suitably fixed.
NOTE: an IPv6 address coerced to an IPv4 address can only be used
for such purposes as rudimentary identification or indexing into a
collection of real InetAddress
es. They cannot be used as
real addresses for the purposes of network communication.
ip
- InetAddress
to convert
int
, "coerced" if ip is not an IPv4 addresspublic static Inet4Address fromInteger(int address)
address
- int
, the 32bit integer address to be converted
Inet4Address
equivalent of the argumentpublic static InetAddress fromLittleEndianByteArray(byte[] addr) throws UnknownHostException
InetAddress.getByAddress(java.lang.String, byte[])
expects).
IPv4 address byte array must be 4 bytes long and IPv6 byte array must be 16 bytes long.
addr
- the raw IP address in little-endian byte order
UnknownHostException
- if IP address is of illegal length
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |