Class InetAddresses
- java.lang.Object
-
- com.google.common.net.InetAddresses
-
@GwtIncompatible public final class InetAddresses extends java.lang.Object
Static utility methods pertaining toInetAddress
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.When dealing with
Inet4Address
andInet6Address
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:
- The IPv4 loopback address,
"127.0.0.1"
. 7f 00 00 01
- The IPv6 loopback address,
"::1"
. 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01
- From the IPv6 reserved documentation prefix (
2001:db8::/32
),"2001:db8::1"
. 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01
- An IPv6 "IPv4 compatible" (or "compat") address,
"::192.168.0.1"
. 00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01
- An IPv6 "IPv4 mapped" address,
"::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:- Since:
- 5.0
- Author:
- Erik Kline
- The IPv4 loopback address,
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
InetAddresses.TeredoInfo
A simple immutable data class to encapsulate the information to be found in a Teredo address.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static int
coerceToInteger(java.net.InetAddress ip)
Returns an integer representing an IPv4 address regardless of whether the supplied argument is an IPv4 address or not.static java.net.InetAddress
decrement(java.net.InetAddress address)
Returns a new InetAddress that is one less than the passed in address.static java.net.InetAddress
forString(java.lang.String ipString)
Returns theInetAddress
having the given string representation.static java.net.InetAddress
forUriString(java.lang.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 java.net.Inet4Address
fromInteger(int address)
Returns an Inet4Address having the integer value specified by the argument.static java.net.Inet4Address
fromIPv4BigInteger(java.math.BigInteger address)
Returns theInet4Address
corresponding to a givenBigInteger
.static java.net.Inet6Address
fromIPv6BigInteger(java.math.BigInteger address)
Returns theInet6Address
corresponding to a givenBigInteger
.static java.net.InetAddress
fromLittleEndianByteArray(byte[] addr)
Returns an address from a little-endian ordered byte array (the opposite of whatInetAddress.getByAddress(java.lang.String, byte[])
expects).static java.net.Inet4Address
get6to4IPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in a 6to4 address.static java.net.Inet4Address
getCoercedIPv4Address(java.net.InetAddress ip)
Coerces an IPv6 address into an IPv4 address.static java.net.Inet4Address
getCompatIPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in an IPv4 compatible address.static java.net.Inet4Address
getEmbeddedIPv4ClientAddress(java.net.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 java.net.Inet4Address
getIsatapIPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in an ISATAP address.static InetAddresses.TeredoInfo
getTeredoInfo(java.net.Inet6Address ip)
Returns the Teredo information embedded in a Teredo address.static boolean
hasEmbeddedIPv4ClientAddress(java.net.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 java.net.InetAddress
increment(java.net.InetAddress address)
Returns a new InetAddress that is one more than the passed in address.static boolean
is6to4Address(java.net.Inet6Address ip)
Evaluates whether the argument is a 6to4 address.static boolean
isCompatIPv4Address(java.net.Inet6Address ip)
Evaluates whether the argument is an IPv6 "compat" address.static boolean
isInetAddress(java.lang.String ipString)
Returnstrue
if the supplied string is a valid IP string literal,false
otherwise.static boolean
isIsatapAddress(java.net.Inet6Address ip)
Evaluates whether the argument is an ISATAP address.static boolean
isMappedIPv4Address(java.lang.String ipString)
Evaluates whether the argument is an "IPv4 mapped" IPv6 address.static boolean
isMaximum(java.net.InetAddress address)
Returns true if the InetAddress is either 255.255.255.255 for IPv4 or ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6.static boolean
isTeredoAddress(java.net.Inet6Address ip)
Evaluates whether the argument is a Teredo address.static boolean
isUriInetAddress(java.lang.String ipString)
Returnstrue
if the supplied string is a valid URI IP string literal,false
otherwise.static java.lang.String
toAddrString(java.net.InetAddress ip)
Returns the string representation of anInetAddress
.static java.math.BigInteger
toBigInteger(java.net.InetAddress address)
Returns a BigInteger representing the address.static java.lang.String
toUriString(java.net.InetAddress ip)
Returns the string representation of anInetAddress
suitable for inclusion in a URI.
-
-
-
Method Detail
-
forString
@CanIgnoreReturnValue public static java.net.InetAddress forString(java.lang.String ipString)
Returns theInetAddress
having the given string representation.This deliberately avoids all nameservice lookups (e.g. no DNS).
This method accepts non-ASCII digits, for example
"192.168.0.1"
(those are fullwidth characters). That is consistent withInetAddress
, but not with various RFCs. If you want to accept ASCII digits only, you can use something likeCharMatcher.ascii().matchesAllOf(ipString)
.The scope ID is validated against the interfaces on the machine, which requires permissions under Android.
Android users on API >= 29: Prefer
InetAddresses.parseNumericAddress
.- Parameters:
ipString
-String
containing an IPv4 or IPv6 string literal, e.g."192.168.0.1"
or"2001:db8::1"
or with a scope ID, e.g."2001:db8::1%eth0"
- Returns:
InetAddress
representing the argument- Throws:
java.lang.IllegalArgumentException
- if the argument is not a valid IP string literal
-
isInetAddress
public static boolean isInetAddress(java.lang.String ipString)
Returnstrue
if the supplied string is a valid IP string literal,false
otherwise.This method accepts non-ASCII digits, for example
"192.168.0.1"
(those are fullwidth characters). That is consistent withInetAddress
, but not with various RFCs. If you want to accept ASCII digits only, you can use something likeCharMatcher.ascii().matchesAllOf(ipString)
.- Parameters:
ipString
-String
to evaluated as an IP string literal- Returns:
true
if the argument is a valid IP string literal
-
toAddrString
public static java.lang.String toAddrString(java.net.InetAddress ip)
Returns the string representation of anInetAddress
.For IPv4 addresses, this is identical to
InetAddress.getHostAddress()
, but for IPv6 addresses, the output follows RFC 5952 section 4. The main difference is that this method uses "::" for zero compression, while Java's version uses the uncompressed form (except on Android, where the zero compression is also done). The other difference is that this method outputs any scope ID in the format that it was provided at creation time, while Android may always output it as an interface name, even if it was supplied as a numeric ID.This method uses hexadecimal for all IPv6 addresses, including IPv4-mapped IPv6 addresses such as "::c000:201".
- Parameters:
ip
-InetAddress
to be converted to an address string- Returns:
String
containing the text-formatted IP address- Since:
- 10.0
-
toUriString
public static java.lang.String toUriString(java.net.InetAddress ip)
Returns the string representation of anInetAddress
suitable for inclusion in a URI.For IPv4 addresses, this is identical to
InetAddress.getHostAddress()
, but for IPv6 addresses it compresses zeroes and surrounds the text with square brackets; for example"[2001:db8::1]"
.Per section 3.2.2 of RFC 3986, a URI containing an IPv6 string literal is of the form
"http://[2001:db8::1]:8888/index.html"
.Use of either
toAddrString(java.net.InetAddress)
,InetAddress.getHostAddress()
, or this method is recommended overInetAddress.toString()
when an IP address string literal is desired. This is becauseInetAddress.toString()
prints the hostname and the IP address string joined by a "/".- Parameters:
ip
-InetAddress
to be converted to URI string literal- Returns:
String
containing URI-safe string literal
-
forUriString
public static java.net.InetAddress forUriString(java.lang.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.This method is similar to
forString(String)
, however, it requires that IPv6 addresses are surrounded by square brackets.This method is the inverse of
toUriString(java.net.InetAddress)
.This method accepts non-ASCII digits, for example
"192.168.0.1"
(those are fullwidth characters). That is consistent withInetAddress
, but not with various RFCs. If you want to accept ASCII digits only, you can use something likeCharMatcher.ascii().matchesAllOf(ipString)
.- Parameters:
hostAddr
- an RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address- Returns:
- an InetAddress representing the address in
hostAddr
- Throws:
java.lang.IllegalArgumentException
- ifhostAddr
is not a valid IPv4 address, or IPv6 address surrounded by square brackets, or if the address has a scope id that fails validation against interfaces on the machine
-
isUriInetAddress
public static boolean isUriInetAddress(java.lang.String ipString)
Returnstrue
if the supplied string is a valid URI IP string literal,false
otherwise.This method accepts non-ASCII digits, for example
"192.168.0.1"
(those are fullwidth characters). That is consistent withInetAddress
, but not with various RFCs. If you want to accept ASCII digits only, you can use something likeCharMatcher.ascii().matchesAllOf(ipString)
.Note that if this method returns
true
, a call toforUriString(String)
can throw if the address has a scope id fails validation against interfaces on the machine.- Parameters:
ipString
-String
to evaluated as an IP URI host string literal- Returns:
true
if the argument is a valid IP URI host
-
isCompatIPv4Address
public static boolean isCompatIPv4Address(java.net.Inet6Address ip)
Evaluates whether the argument is an IPv6 "compat" address.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 RFC 4291.
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).- Parameters:
ip
-Inet6Address
to be examined for embedded IPv4 compatible address format- Returns:
true
if the argument is a valid "compat" address
-
getCompatIPv4Address
public static java.net.Inet4Address getCompatIPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in an IPv4 compatible address.- Parameters:
ip
-Inet6Address
to be examined for an embedded IPv4 address- Returns:
Inet4Address
of the embedded IPv4 address- Throws:
java.lang.IllegalArgumentException
- if the argument is not a valid IPv4 compatible address
-
is6to4Address
public static boolean is6to4Address(java.net.Inet6Address ip)
Evaluates whether the argument is a 6to4 address.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 RFC 3056.
- Parameters:
ip
-Inet6Address
to be examined for 6to4 address format- Returns:
true
if the argument is a 6to4 address
-
get6to4IPv4Address
public static java.net.Inet4Address get6to4IPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in a 6to4 address.- Parameters:
ip
-Inet6Address
to be examined for embedded IPv4 in 6to4 address- Returns:
Inet4Address
of embedded IPv4 in 6to4 address- Throws:
java.lang.IllegalArgumentException
- if the argument is not a valid IPv6 6to4 address
-
isTeredoAddress
public static boolean isTeredoAddress(java.net.Inet6Address ip)
Evaluates whether the argument is a Teredo address.Teredo addresses begin with the
"2001::/32"
prefix.- Parameters:
ip
-Inet6Address
to be examined for Teredo address format- Returns:
true
if the argument is a Teredo address
-
getTeredoInfo
public static InetAddresses.TeredoInfo getTeredoInfo(java.net.Inet6Address ip)
Returns the Teredo information embedded in a Teredo address.- Parameters:
ip
-Inet6Address
to be examined for embedded Teredo information- Returns:
- extracted
TeredoInfo
- Throws:
java.lang.IllegalArgumentException
- if the argument is not a valid IPv6 Teredo address
-
isIsatapAddress
public static boolean isIsatapAddress(java.net.Inet6Address ip)
Evaluates whether the argument is an ISATAP address.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 RFC 5214.
- Parameters:
ip
-Inet6Address
to be examined for ISATAP address format- Returns:
true
if the argument is an ISATAP address
-
getIsatapIPv4Address
public static java.net.Inet4Address getIsatapIPv4Address(java.net.Inet6Address ip)
Returns the IPv4 address embedded in an ISATAP address.- Parameters:
ip
-Inet6Address
to be examined for embedded IPv4 in ISATAP address- Returns:
Inet4Address
of embedded IPv4 in an ISATAP address- Throws:
java.lang.IllegalArgumentException
- if the argument is not a valid IPv6 ISATAP address
-
hasEmbeddedIPv4ClientAddress
public static boolean hasEmbeddedIPv4ClientAddress(java.net.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.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.
- Parameters:
ip
-Inet6Address
to be examined for embedded IPv4 client address- Returns:
true
if there is an embedded IPv4 client address- Since:
- 7.0
-
getEmbeddedIPv4ClientAddress
public static java.net.Inet4Address getEmbeddedIPv4ClientAddress(java.net.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.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.
- Parameters:
ip
-Inet6Address
to be examined for embedded IPv4 client address- Returns:
Inet4Address
of embedded IPv4 client address- Throws:
java.lang.IllegalArgumentException
- if the argument does not have a valid embedded IPv4 address
-
isMappedIPv4Address
public static boolean isMappedIPv4Address(java.lang.String ipString)
Evaluates whether the argument is an "IPv4 mapped" IPv6 address.An "IPv4 mapped" address is anything in the range ::ffff:0:0/96 (sometimes written as ::ffff:0.0.0.0/96), with the last 32 bits interpreted as an IPv4 address.
For more on IPv4 mapped addresses see section 2.5.5.2 of RFC 4291.
Note: This method takes a
String
argument becauseInetAddress
automatically collapses mapped addresses to IPv4. (It is actually possible to avoid this using one of the obscureInet6Address
methods, but it would be unwise to depend on such a poorly-documented feature.)This method accepts non-ASCII digits. That is consistent with
InetAddress
, but not with various RFCs. If you want to accept ASCII digits only, you can use something likeCharMatcher.ascii().matchesAllOf(ipString)
.- Parameters:
ipString
-String
to be examined for embedded IPv4-mapped IPv6 address format- Returns:
true
if the argument is a valid "mapped" address- Since:
- 10.0
-
getCoercedIPv4Address
public static java.net.Inet4Address getCoercedIPv4Address(java.net.InetAddress ip)
Coerces an IPv6 address into an IPv4 address.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 method does so by hashing 64 bits of the IPv6 address into
224.0.0.0/3
(64 bits into 29 bits):- If the IPv6 address contains an embedded IPv4 address, the function hashes that.
- Otherwise, it hashes the upper 64 bits of the IPv6 address.
A "coerced" IPv4 address is equivalent to itself.
NOTE: This method 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.
- Parameters:
ip
-InetAddress
to "coerce"- Returns:
Inet4Address
represented "coerced" address- Since:
- 7.0
-
coerceToInteger
public static int coerceToInteger(java.net.InetAddress ip)
Returns an integer representing an IPv4 address regardless of whether the supplied argument is an IPv4 address or not.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.- Parameters:
ip
-InetAddress
to convert- Returns:
int
, "coerced" if ip is not an IPv4 address- Since:
- 7.0
-
toBigInteger
public static java.math.BigInteger toBigInteger(java.net.InetAddress address)
Returns a BigInteger representing the address.Unlike
coerceToInteger
, IPv6 addresses are not coerced to IPv4 addresses.- Parameters:
address
-InetAddress
to convert- Returns:
BigInteger
representation of the address- Since:
- 28.2
-
fromInteger
public static java.net.Inet4Address fromInteger(int address)
Returns an Inet4Address having the integer value specified by the argument.- Parameters:
address
-int
, the 32bit integer address to be converted- Returns:
Inet4Address
equivalent of the argument
-
fromIPv4BigInteger
public static java.net.Inet4Address fromIPv4BigInteger(java.math.BigInteger address)
Returns theInet4Address
corresponding to a givenBigInteger
.- Parameters:
address
- BigInteger representing the IPv4 address- Returns:
- Inet4Address representation of the given BigInteger
- Throws:
java.lang.IllegalArgumentException
- if the BigInteger is not between 0 and 2^32-1- Since:
- 28.2
-
fromIPv6BigInteger
public static java.net.Inet6Address fromIPv6BigInteger(java.math.BigInteger address)
Returns theInet6Address
corresponding to a givenBigInteger
.- Parameters:
address
- BigInteger representing the IPv6 address- Returns:
- Inet6Address representation of the given BigInteger
- Throws:
java.lang.IllegalArgumentException
- if the BigInteger is not between 0 and 2^128-1- Since:
- 28.2
-
fromLittleEndianByteArray
public static java.net.InetAddress fromLittleEndianByteArray(byte[] addr) throws java.net.UnknownHostException
Returns an address from a little-endian ordered byte array (the opposite of whatInetAddress.getByAddress(java.lang.String, byte[])
expects).IPv4 address byte array must be 4 bytes long and IPv6 byte array must be 16 bytes long.
- Parameters:
addr
- the raw IP address in little-endian byte order- Returns:
- an InetAddress object created from the raw IP address
- Throws:
java.net.UnknownHostException
- if IP address is of illegal length
-
decrement
public static java.net.InetAddress decrement(java.net.InetAddress address)
Returns a new InetAddress that is one less than the passed in address. This method works for both IPv4 and IPv6 addresses.- Parameters:
address
- the InetAddress to decrement- Returns:
- a new InetAddress that is one less than the passed in address
- Throws:
java.lang.IllegalArgumentException
- if InetAddress is at the beginning of its range- Since:
- 18.0
-
increment
public static java.net.InetAddress increment(java.net.InetAddress address)
Returns a new InetAddress that is one more than the passed in address. This method works for both IPv4 and IPv6 addresses.- Parameters:
address
- the InetAddress to increment- Returns:
- a new InetAddress that is one more than the passed in address
- Throws:
java.lang.IllegalArgumentException
- if InetAddress is at the end of its range- Since:
- 10.0
-
isMaximum
public static boolean isMaximum(java.net.InetAddress address)
Returns true if the InetAddress is either 255.255.255.255 for IPv4 or ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6.- Returns:
- true if the InetAddress is either 255.255.255.255 for IPv4 or ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6
- Since:
- 10.0
-
-