001/*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.net;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static java.lang.Math.max;
020import static java.util.Objects.requireNonNull;
021
022import com.google.common.annotations.GwtIncompatible;
023import com.google.common.annotations.J2ktIncompatible;
024import com.google.common.base.CharMatcher;
025import com.google.common.base.MoreObjects;
026import com.google.common.hash.Hashing;
027import com.google.common.io.ByteStreams;
028import com.google.common.primitives.Ints;
029import com.google.errorprone.annotations.CanIgnoreReturnValue;
030import java.math.BigInteger;
031import java.net.Inet4Address;
032import java.net.Inet6Address;
033import java.net.InetAddress;
034import java.net.NetworkInterface;
035import java.net.SocketException;
036import java.net.UnknownHostException;
037import java.nio.ByteBuffer;
038import java.util.Arrays;
039import java.util.Locale;
040import javax.annotation.CheckForNull;
041import org.checkerframework.checker.nullness.qual.Nullable;
042
043/**
044 * Static utility methods pertaining to {@link InetAddress} instances.
045 *
046 * <p><b>Important note:</b> Unlike {@code InetAddress.getByName()}, the methods of this class never
047 * cause DNS services to be accessed. For this reason, you should prefer these methods as much as
048 * possible over their JDK equivalents whenever you are expecting to handle only IP address string
049 * literals -- there is no blocking DNS penalty for a malformed string.
050 *
051 * <p>When dealing with {@link Inet4Address} and {@link Inet6Address} objects as byte arrays (vis.
052 * {@code InetAddress.getAddress()}) they are 4 and 16 bytes in length, respectively, and represent
053 * the address in network byte order.
054 *
055 * <p>Examples of IP addresses and their byte representations:
056 *
057 * <dl>
058 *   <dt>The IPv4 loopback address, {@code "127.0.0.1"}.
059 *   <dd>{@code 7f 00 00 01}
060 *   <dt>The IPv6 loopback address, {@code "::1"}.
061 *   <dd>{@code 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01}
062 *   <dt>From the IPv6 reserved documentation prefix ({@code 2001:db8::/32}), {@code "2001:db8::1"}.
063 *   <dd>{@code 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01}
064 *   <dt>An IPv6 "IPv4 compatible" (or "compat") address, {@code "::192.168.0.1"}.
065 *   <dd>{@code 00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01}
066 *   <dt>An IPv6 "IPv4 mapped" address, {@code "::ffff:192.168.0.1"}.
067 *   <dd>{@code 00 00 00 00 00 00 00 00 00 00 ff ff c0 a8 00 01}
068 * </dl>
069 *
070 * <p>A few notes about IPv6 "IPv4 mapped" addresses and their observed use in Java.
071 *
072 * <p>"IPv4 mapped" addresses were originally a representation of IPv4 addresses for use on an IPv6
073 * socket that could receive both IPv4 and IPv6 connections (by disabling the {@code IPV6_V6ONLY}
074 * socket option on an IPv6 socket). Yes, it's confusing. Nevertheless, these "mapped" addresses
075 * were never supposed to be seen on the wire. That assumption was dropped, some say mistakenly, in
076 * later RFCs with the apparent aim of making IPv4-to-IPv6 transition simpler.
077 *
078 * <p>Technically one <i>can</i> create a 128bit IPv6 address with the wire format of a "mapped"
079 * address, as shown above, and transmit it in an IPv6 packet header. However, Java's InetAddress
080 * creation methods appear to adhere doggedly to the original intent of the "mapped" address: all
081 * "mapped" addresses return {@link Inet4Address} objects.
082 *
083 * <p>For added safety, it is common for IPv6 network operators to filter all packets where either
084 * the source or destination address appears to be a "compat" or "mapped" address. Filtering
085 * suggestions usually recommend discarding any packets with source or destination addresses in the
086 * invalid range {@code ::/3}, which includes both of these bizarre address formats. For more
087 * information on "bogons", including lists of IPv6 bogon space, see:
088 *
089 * <ul>
090 *   <li><a target="_parent"
091 *       href="http://en.wikipedia.org/wiki/Bogon_filtering">http://en.wikipedia.
092 *       org/wiki/Bogon_filtering</a>
093 *   <li><a target="_parent"
094 *       href="http://www.cymru.com/Bogons/ipv6.txt">http://www.cymru.com/Bogons/ ipv6.txt</a>
095 *   <li><a target="_parent" href="http://www.cymru.com/Bogons/v6bogon.html">http://www.cymru.com/
096 *       Bogons/v6bogon.html</a>
097 *   <li><a target="_parent" href="http://www.space.net/~gert/RIPE/ipv6-filters.html">http://www.
098 *       space.net/~gert/RIPE/ipv6-filters.html</a>
099 * </ul>
100 *
101 * @author Erik Kline
102 * @since 5.0
103 */
104@J2ktIncompatible
105@GwtIncompatible
106public final class InetAddresses {
107  private static final int IPV4_PART_COUNT = 4;
108  private static final int IPV6_PART_COUNT = 8;
109  private static final char IPV4_DELIMITER = '.';
110  private static final char IPV6_DELIMITER = ':';
111  private static final CharMatcher IPV4_DELIMITER_MATCHER = CharMatcher.is(IPV4_DELIMITER);
112  private static final CharMatcher IPV6_DELIMITER_MATCHER = CharMatcher.is(IPV6_DELIMITER);
113  private static final Inet4Address LOOPBACK4 = (Inet4Address) forString("127.0.0.1");
114  private static final Inet4Address ANY4 = (Inet4Address) forString("0.0.0.0");
115
116  private InetAddresses() {}
117
118  /**
119   * Returns an {@link Inet4Address}, given a byte array representation of the IPv4 address.
120   *
121   * @param bytes byte array representing an IPv4 address (should be of length 4)
122   * @return {@link Inet4Address} corresponding to the supplied byte array
123   * @throws IllegalArgumentException if a valid {@link Inet4Address} can not be created
124   */
125  private static Inet4Address getInet4Address(byte[] bytes) {
126    checkArgument(
127        bytes.length == 4,
128        "Byte array has invalid length for an IPv4 address: %s != 4.",
129        bytes.length);
130
131    // Given a 4-byte array, this cast should always succeed.
132    return (Inet4Address) bytesToInetAddress(bytes, null);
133  }
134
135  /**
136   * Returns the {@link InetAddress} having the given string representation.
137   *
138   * <p>This deliberately avoids all nameservice lookups (e.g. no DNS).
139   *
140   * <p>This method accepts non-ASCII digits, for example {@code "192.168.0.1"} (those are fullwidth
141   * characters). That is consistent with {@link InetAddress}, but not with various RFCs. If you
142   * want to accept ASCII digits only, you can use something like {@code
143   * CharMatcher.ascii().matchesAllOf(ipString)}.
144   *
145   * <p>The scope ID is validated against the interfaces on the machine, which requires permissions
146   * under Android.
147   *
148   * <p><b>Android users on API >= 29:</b> Prefer {@code InetAddresses.parseNumericAddress}.
149   *
150   * @param ipString {@code String} containing an IPv4 or IPv6 string literal, e.g. {@code
151   *     "192.168.0.1"} or {@code "2001:db8::1"} or with a scope ID, e.g. {@code "2001:db8::1%eth0"}
152   * @return {@link InetAddress} representing the argument
153   * @throws IllegalArgumentException if the argument is not a valid IP string literal or if the
154   *     address has a scope ID that fails validation against the interfaces on the machine (as
155   *     required by Java's {@link InetAddress})
156   */
157  @CanIgnoreReturnValue // TODO(b/219820829): consider removing
158  public static InetAddress forString(String ipString) {
159    Scope scope = new Scope();
160    byte[] addr = ipStringToBytes(ipString, scope);
161
162    // The argument was malformed, i.e. not an IP string literal.
163    if (addr == null) {
164      throw formatIllegalArgumentException("'%s' is not an IP string literal.", ipString);
165    }
166
167    return bytesToInetAddress(addr, scope.scope);
168  }
169
170  /**
171   * Returns {@code true} if the supplied string is a valid IP string literal, {@code false}
172   * otherwise.
173   *
174   * <p>This method accepts non-ASCII digits, for example {@code "192.168.0.1"} (those are fullwidth
175   * characters). That is consistent with {@link InetAddress}, but not with various RFCs. If you
176   * want to accept ASCII digits only, you can use something like {@code
177   * CharMatcher.ascii().matchesAllOf(ipString)}.
178   *
179   * <p>Note that if this method returns {@code true}, a call to {@link #forString(String)} can
180   * still throw if the address has a scope ID that fails validation against the interfaces on the
181   * machine.
182   *
183   * @param ipString {@code String} to evaluated as an IP string literal
184   * @return {@code true} if the argument is a valid IP string literal
185   */
186  public static boolean isInetAddress(String ipString) {
187    return ipStringToBytes(ipString, null) != null;
188  }
189
190  private static final class Scope {
191    private String scope;
192  }
193
194  /** Returns {@code null} if unable to parse into a {@code byte[]}. */
195  @CheckForNull
196  private static byte[] ipStringToBytes(String ipStringParam, @Nullable Scope scope) {
197    String ipString = ipStringParam;
198    // Make a first pass to categorize the characters in this string.
199    boolean hasColon = false;
200    boolean hasDot = false;
201    int percentIndex = -1;
202    for (int i = 0; i < ipString.length(); i++) {
203      char c = ipString.charAt(i);
204      if (c == '.') {
205        hasDot = true;
206      } else if (c == ':') {
207        if (hasDot) {
208          return null; // Colons must not appear after dots.
209        }
210        hasColon = true;
211      } else if (c == '%') {
212        percentIndex = i;
213        break;
214      } else if (Character.digit(c, 16) == -1) {
215        return null; // Everything else must be a decimal or hex digit.
216      }
217    }
218
219    // Now decide which address family to parse.
220    if (hasColon) {
221      if (hasDot) {
222        ipString = convertDottedQuadToHex(ipString);
223        if (ipString == null) {
224          return null;
225        }
226      }
227      if (percentIndex != -1) {
228        if (scope != null) {
229          scope.scope = ipString.substring(percentIndex + 1);
230        }
231        ipString = ipString.substring(0, percentIndex);
232      }
233      return textToNumericFormatV6(ipString);
234    } else if (hasDot) {
235      if (percentIndex != -1) {
236        return null; // Scope IDs are not supported for IPV4
237      }
238      return textToNumericFormatV4(ipString);
239    }
240    return null;
241  }
242
243  @CheckForNull
244  private static byte[] textToNumericFormatV4(String ipString) {
245    if (IPV4_DELIMITER_MATCHER.countIn(ipString) + 1 != IPV4_PART_COUNT) {
246      return null; // Wrong number of parts
247    }
248
249    byte[] bytes = new byte[IPV4_PART_COUNT];
250    int start = 0;
251    // Iterate through the parts of the ip string.
252    // Invariant: start is always the beginning of an octet.
253    for (int i = 0; i < IPV4_PART_COUNT; i++) {
254      int end = ipString.indexOf(IPV4_DELIMITER, start);
255      if (end == -1) {
256        end = ipString.length();
257      }
258      try {
259        bytes[i] = parseOctet(ipString, start, end);
260      } catch (NumberFormatException ex) {
261        return null;
262      }
263      start = end + 1;
264    }
265
266    return bytes;
267  }
268
269  @CheckForNull
270  private static byte[] textToNumericFormatV6(String ipString) {
271    // An address can have [2..8] colons.
272    int delimiterCount = IPV6_DELIMITER_MATCHER.countIn(ipString);
273    if (delimiterCount < 2 || delimiterCount > IPV6_PART_COUNT) {
274      return null;
275    }
276    int partsSkipped = IPV6_PART_COUNT - (delimiterCount + 1); // estimate; may be modified later
277    boolean hasSkip = false;
278    // Scan for the appearance of ::, to mark a skip-format IPV6 string and adjust the partsSkipped
279    // estimate.
280    for (int i = 0; i < ipString.length() - 1; i++) {
281      if (ipString.charAt(i) == IPV6_DELIMITER && ipString.charAt(i + 1) == IPV6_DELIMITER) {
282        if (hasSkip) {
283          return null; // Can't have more than one ::
284        }
285        hasSkip = true;
286        partsSkipped++; // :: means we skipped an extra part in between the two delimiters.
287        if (i == 0) {
288          partsSkipped++; // Begins with ::, so we skipped the part preceding the first :
289        }
290        if (i == ipString.length() - 2) {
291          partsSkipped++; // Ends with ::, so we skipped the part after the last :
292        }
293      }
294    }
295    if (ipString.charAt(0) == IPV6_DELIMITER && ipString.charAt(1) != IPV6_DELIMITER) {
296      return null; // ^: requires ^::
297    }
298    if (ipString.charAt(ipString.length() - 1) == IPV6_DELIMITER
299        && ipString.charAt(ipString.length() - 2) != IPV6_DELIMITER) {
300      return null; // :$ requires ::$
301    }
302    if (hasSkip && partsSkipped <= 0) {
303      return null; // :: must expand to at least one '0'
304    }
305    if (!hasSkip && delimiterCount + 1 != IPV6_PART_COUNT) {
306      return null; // Incorrect number of parts
307    }
308
309    ByteBuffer rawBytes = ByteBuffer.allocate(2 * IPV6_PART_COUNT);
310    try {
311      // Iterate through the parts of the ip string.
312      // Invariant: start is always the beginning of a hextet, or the second ':' of the skip
313      // sequence "::"
314      int start = 0;
315      if (ipString.charAt(0) == IPV6_DELIMITER) {
316        start = 1;
317      }
318      while (start < ipString.length()) {
319        int end = ipString.indexOf(IPV6_DELIMITER, start);
320        if (end == -1) {
321          end = ipString.length();
322        }
323        if (ipString.charAt(start) == IPV6_DELIMITER) {
324          // expand zeroes
325          for (int i = 0; i < partsSkipped; i++) {
326            rawBytes.putShort((short) 0);
327          }
328
329        } else {
330          rawBytes.putShort(parseHextet(ipString, start, end));
331        }
332        start = end + 1;
333      }
334    } catch (NumberFormatException ex) {
335      return null;
336    }
337    return rawBytes.array();
338  }
339
340  @CheckForNull
341  private static String convertDottedQuadToHex(String ipString) {
342    int lastColon = ipString.lastIndexOf(':');
343    String initialPart = ipString.substring(0, lastColon + 1);
344    String dottedQuad = ipString.substring(lastColon + 1);
345    byte[] quad = textToNumericFormatV4(dottedQuad);
346    if (quad == null) {
347      return null;
348    }
349    String penultimate = Integer.toHexString(((quad[0] & 0xff) << 8) | (quad[1] & 0xff));
350    String ultimate = Integer.toHexString(((quad[2] & 0xff) << 8) | (quad[3] & 0xff));
351    return initialPart + penultimate + ":" + ultimate;
352  }
353
354  private static byte parseOctet(String ipString, int start, int end) {
355    // Note: we already verified that this string contains only hex digits, but the string may still
356    // contain non-decimal characters.
357    int length = end - start;
358    if (length <= 0 || length > 3) {
359      throw new NumberFormatException();
360    }
361    // Disallow leading zeroes, because no clear standard exists on
362    // whether these should be interpreted as decimal or octal.
363    if (length > 1 && ipString.charAt(start) == '0') {
364      throw new NumberFormatException();
365    }
366    int octet = 0;
367    for (int i = start; i < end; i++) {
368      octet *= 10;
369      int digit = Character.digit(ipString.charAt(i), 10);
370      if (digit < 0) {
371        throw new NumberFormatException();
372      }
373      octet += digit;
374    }
375    if (octet > 255) {
376      throw new NumberFormatException();
377    }
378    return (byte) octet;
379  }
380
381  /** Returns a -1 if unable to parse */
382  private static int tryParseDecimal(String string, int start, int end) {
383    int decimal = 0;
384    final int max = Integer.MAX_VALUE / 10; // for int overflow detection
385    for (int i = start; i < end; i++) {
386      if (decimal > max) {
387        return -1;
388      }
389      decimal *= 10;
390      int digit = Character.digit(string.charAt(i), 10);
391      if (digit < 0) {
392        return -1;
393      }
394      decimal += digit;
395    }
396    return decimal;
397  }
398
399  // Parse a hextet out of the ipString from start (inclusive) to end (exclusive)
400  private static short parseHextet(String ipString, int start, int end) {
401    // Note: we already verified that this string contains only hex digits.
402    int length = end - start;
403    if (length <= 0 || length > 4) {
404      throw new NumberFormatException();
405    }
406    int hextet = 0;
407    for (int i = start; i < end; i++) {
408      hextet = hextet << 4;
409      hextet |= Character.digit(ipString.charAt(i), 16);
410    }
411    return (short) hextet;
412  }
413
414  /**
415   * Convert a byte array into an InetAddress.
416   *
417   * <p>{@link InetAddress#getByAddress} is documented as throwing a checked exception "if IP
418   * address is of illegal length." We replace it with an unchecked exception, for use by callers
419   * who already know that addr is an array of length 4 or 16.
420   *
421   * @param addr the raw 4-byte or 16-byte IP address in big-endian order
422   * @return an InetAddress object created from the raw IP address
423   */
424  private static InetAddress bytesToInetAddress(byte[] addr, @Nullable String scope) {
425    try {
426      InetAddress address = InetAddress.getByAddress(addr);
427      if (scope == null) {
428        return address;
429      }
430      checkArgument(
431          address instanceof Inet6Address, "Unexpected state, scope should only appear for ipv6");
432      Inet6Address v6Address = (Inet6Address) address;
433      int interfaceIndex = tryParseDecimal(scope, 0, scope.length());
434      if (interfaceIndex != -1) {
435        return Inet6Address.getByAddress(
436            v6Address.getHostAddress(), v6Address.getAddress(), interfaceIndex);
437      }
438      try {
439        NetworkInterface asInterface = NetworkInterface.getByName(scope);
440        if (asInterface == null) {
441          throw formatIllegalArgumentException("No such interface: '%s'", scope);
442        }
443        return Inet6Address.getByAddress(
444            v6Address.getHostAddress(), v6Address.getAddress(), asInterface);
445      } catch (SocketException | UnknownHostException e) {
446        throw new IllegalArgumentException("No such interface: " + scope, e);
447      }
448    } catch (UnknownHostException e) {
449      throw new AssertionError(e);
450    }
451  }
452
453  /**
454   * Returns the string representation of an {@link InetAddress}.
455   *
456   * <p>For IPv4 addresses, this is identical to {@link InetAddress#getHostAddress()}, but for IPv6
457   * addresses, the output follows <a href="http://tools.ietf.org/html/rfc5952">RFC 5952</a> section
458   * 4. The main difference is that this method uses "::" for zero compression, while Java's version
459   * uses the uncompressed form (except on Android, where the zero compression is also done). The
460   * other difference is that this method outputs any scope ID in the format that it was provided at
461   * creation time, while Android may always output it as an interface name, even if it was supplied
462   * as a numeric ID.
463   *
464   * <p>This method uses hexadecimal for all IPv6 addresses, including IPv4-mapped IPv6 addresses
465   * such as "::c000:201".
466   *
467   * @param ip {@link InetAddress} to be converted to an address string
468   * @return {@code String} containing the text-formatted IP address
469   * @since 10.0
470   */
471  public static String toAddrString(InetAddress ip) {
472    checkNotNull(ip);
473    if (ip instanceof Inet4Address) {
474      // For IPv4, Java's formatting is good enough.
475      // requireNonNull accommodates Android's @RecentlyNullable annotation on getHostAddress
476      return requireNonNull(ip.getHostAddress());
477    }
478    byte[] bytes = ip.getAddress();
479    int[] hextets = new int[IPV6_PART_COUNT];
480    for (int i = 0; i < hextets.length; i++) {
481      hextets[i] = Ints.fromBytes((byte) 0, (byte) 0, bytes[2 * i], bytes[2 * i + 1]);
482    }
483    compressLongestRunOfZeroes(hextets);
484
485    return hextetsToIPv6String(hextets) + scopeWithDelimiter((Inet6Address) ip);
486  }
487
488  private static String scopeWithDelimiter(Inet6Address ip) {
489    // getHostAddress on android sometimes maps the scope ID to an invalid interface name; if the
490    // mapped interface isn't present, fallback to use the scope ID (which has no validation against
491    // present interfaces)
492    NetworkInterface scopedInterface = ip.getScopedInterface();
493    if (scopedInterface != null) {
494      return "%" + scopedInterface.getName();
495    }
496    int scope = ip.getScopeId();
497    if (scope != 0) {
498      return "%" + scope;
499    }
500    return "";
501  }
502
503  /**
504   * Identify and mark the longest run of zeroes in an IPv6 address.
505   *
506   * <p>Only runs of two or more hextets are considered. In case of a tie, the leftmost run wins. If
507   * a qualifying run is found, its hextets are replaced by the sentinel value -1.
508   *
509   * @param hextets {@code int[]} mutable array of eight 16-bit hextets
510   */
511  private static void compressLongestRunOfZeroes(int[] hextets) {
512    int bestRunStart = -1;
513    int bestRunLength = -1;
514    int runStart = -1;
515    for (int i = 0; i < hextets.length + 1; i++) {
516      if (i < hextets.length && hextets[i] == 0) {
517        if (runStart < 0) {
518          runStart = i;
519        }
520      } else if (runStart >= 0) {
521        int runLength = i - runStart;
522        if (runLength > bestRunLength) {
523          bestRunStart = runStart;
524          bestRunLength = runLength;
525        }
526        runStart = -1;
527      }
528    }
529    if (bestRunLength >= 2) {
530      Arrays.fill(hextets, bestRunStart, bestRunStart + bestRunLength, -1);
531    }
532  }
533
534  /**
535   * Convert a list of hextets into a human-readable IPv6 address.
536   *
537   * <p>In order for "::" compression to work, the input should contain negative sentinel values in
538   * place of the elided zeroes.
539   *
540   * @param hextets {@code int[]} array of eight 16-bit hextets, or -1s
541   */
542  private static String hextetsToIPv6String(int[] hextets) {
543    // While scanning the array, handle these state transitions:
544    //   start->num => "num"     start->gap => "::"
545    //   num->num   => ":num"    num->gap   => "::"
546    //   gap->num   => "num"     gap->gap   => ""
547    StringBuilder buf = new StringBuilder(39);
548    boolean lastWasNumber = false;
549    for (int i = 0; i < hextets.length; i++) {
550      boolean thisIsNumber = hextets[i] >= 0;
551      if (thisIsNumber) {
552        if (lastWasNumber) {
553          buf.append(':');
554        }
555        buf.append(Integer.toHexString(hextets[i]));
556      } else {
557        if (i == 0 || lastWasNumber) {
558          buf.append("::");
559        }
560      }
561      lastWasNumber = thisIsNumber;
562    }
563    return buf.toString();
564  }
565
566  /**
567   * Returns the string representation of an {@link InetAddress} suitable for inclusion in a URI.
568   *
569   * <p>For IPv4 addresses, this is identical to {@link InetAddress#getHostAddress()}, but for IPv6
570   * addresses it compresses zeroes and surrounds the text with square brackets; for example {@code
571   * "[2001:db8::1]"}.
572   *
573   * <p>Per section 3.2.2 of <a target="_parent"
574   * href="http://tools.ietf.org/html/rfc3986#section-3.2.2">RFC 3986</a>, a URI containing an IPv6
575   * string literal is of the form {@code "http://[2001:db8::1]:8888/index.html"}.
576   *
577   * <p>Use of either {@link InetAddresses#toAddrString}, {@link InetAddress#getHostAddress()}, or
578   * this method is recommended over {@link InetAddress#toString()} when an IP address string
579   * literal is desired. This is because {@link InetAddress#toString()} prints the hostname and the
580   * IP address string joined by a "/".
581   *
582   * @param ip {@link InetAddress} to be converted to URI string literal
583   * @return {@code String} containing URI-safe string literal
584   */
585  public static String toUriString(InetAddress ip) {
586    if (ip instanceof Inet6Address) {
587      return "[" + toAddrString(ip) + "]";
588    }
589    return toAddrString(ip);
590  }
591
592  /**
593   * Returns an InetAddress representing the literal IPv4 or IPv6 host portion of a URL, encoded in
594   * the format specified by RFC 3986 section 3.2.2.
595   *
596   * <p>This method is similar to {@link InetAddresses#forString(String)}, however, it requires that
597   * IPv6 addresses are surrounded by square brackets.
598   *
599   * <p>This method is the inverse of {@link InetAddresses#toUriString(java.net.InetAddress)}.
600   *
601   * <p>This method accepts non-ASCII digits, for example {@code "192.168.0.1"} (those are fullwidth
602   * characters). That is consistent with {@link InetAddress}, but not with various RFCs. If you
603   * want to accept ASCII digits only, you can use something like {@code
604   * CharMatcher.ascii().matchesAllOf(ipString)}.
605   *
606   * @param hostAddr an RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address
607   * @return an InetAddress representing the address in {@code hostAddr}
608   * @throws IllegalArgumentException if {@code hostAddr} is not a valid IPv4 address, or IPv6
609   *     address surrounded by square brackets, or if the address has a scope ID that fails
610   *     validation against the interfaces on the machine (as required by Java's {@link
611   *     InetAddress})
612   */
613  public static InetAddress forUriString(String hostAddr) {
614    InetAddress addr = forUriStringOrNull(hostAddr, /* parseScope= */ true);
615    if (addr == null) {
616      throw formatIllegalArgumentException("Not a valid URI IP literal: '%s'", hostAddr);
617    }
618
619    return addr;
620  }
621
622  @CheckForNull
623  private static InetAddress forUriStringOrNull(String hostAddr, boolean parseScope) {
624    checkNotNull(hostAddr);
625
626    // Decide if this should be an IPv6 or IPv4 address.
627    String ipString;
628    int expectBytes;
629    if (hostAddr.startsWith("[") && hostAddr.endsWith("]")) {
630      ipString = hostAddr.substring(1, hostAddr.length() - 1);
631      expectBytes = 16;
632    } else {
633      ipString = hostAddr;
634      expectBytes = 4;
635    }
636
637    // Parse the address, and make sure the length/version is correct.
638    Scope scope = parseScope ? new Scope() : null;
639    byte[] addr = ipStringToBytes(ipString, scope);
640    if (addr == null || addr.length != expectBytes) {
641      return null;
642    }
643
644    return bytesToInetAddress(addr, (scope != null) ? scope.scope : null);
645  }
646
647  /**
648   * Returns {@code true} if the supplied string is a valid URI IP string literal, {@code false}
649   * otherwise.
650   *
651   * <p>This method accepts non-ASCII digits, for example {@code "192.168.0.1"} (those are fullwidth
652   * characters). That is consistent with {@link InetAddress}, but not with various RFCs. If you
653   * want to accept ASCII digits only, you can use something like {@code
654   * CharMatcher.ascii().matchesAllOf(ipString)}.
655   *
656   * <p>Note that if this method returns {@code true}, a call to {@link #forUriString(String)} can
657   * still throw if the address has a scope ID that fails validation against the interfaces on the
658   * machine.
659   *
660   * @param ipString {@code String} to evaluated as an IP URI host string literal
661   * @return {@code true} if the argument is a valid IP URI host
662   */
663  public static boolean isUriInetAddress(String ipString) {
664    return forUriStringOrNull(ipString, /* parseScope= */ false) != null;
665  }
666
667  /**
668   * Evaluates whether the argument is an IPv6 "compat" address.
669   *
670   * <p>An "IPv4 compatible", or "compat", address is one with 96 leading bits of zero, with the
671   * remaining 32 bits interpreted as an IPv4 address. These are conventionally represented in
672   * string literals as {@code "::192.168.0.1"}, though {@code "::c0a8:1"} is also considered an
673   * IPv4 compatible address (and equivalent to {@code "::192.168.0.1"}).
674   *
675   * <p>For more on IPv4 compatible addresses see section 2.5.5.1 of <a target="_parent"
676   * href="http://tools.ietf.org/html/rfc4291#section-2.5.5.1">RFC 4291</a>.
677   *
678   * <p>NOTE: This method is different from {@link Inet6Address#isIPv4CompatibleAddress} in that it
679   * more correctly classifies {@code "::"} and {@code "::1"} as proper IPv6 addresses (which they
680   * are), NOT IPv4 compatible addresses (which they are generally NOT considered to be).
681   *
682   * @param ip {@link Inet6Address} to be examined for embedded IPv4 compatible address format
683   * @return {@code true} if the argument is a valid "compat" address
684   */
685  public static boolean isCompatIPv4Address(Inet6Address ip) {
686    if (!ip.isIPv4CompatibleAddress()) {
687      return false;
688    }
689
690    byte[] bytes = ip.getAddress();
691    if ((bytes[12] == 0)
692        && (bytes[13] == 0)
693        && (bytes[14] == 0)
694        && ((bytes[15] == 0) || (bytes[15] == 1))) {
695      return false;
696    }
697
698    return true;
699  }
700
701  /**
702   * Returns the IPv4 address embedded in an IPv4 compatible address.
703   *
704   * @param ip {@link Inet6Address} to be examined for an embedded IPv4 address
705   * @return {@link Inet4Address} of the embedded IPv4 address
706   * @throws IllegalArgumentException if the argument is not a valid IPv4 compatible address
707   */
708  public static Inet4Address getCompatIPv4Address(Inet6Address ip) {
709    checkArgument(
710        isCompatIPv4Address(ip), "Address '%s' is not IPv4-compatible.", toAddrString(ip));
711
712    return getInet4Address(Arrays.copyOfRange(ip.getAddress(), 12, 16));
713  }
714
715  /**
716   * Evaluates whether the argument is a 6to4 address.
717   *
718   * <p>6to4 addresses begin with the {@code "2002::/16"} prefix. The next 32 bits are the IPv4
719   * address of the host to which IPv6-in-IPv4 tunneled packets should be routed.
720   *
721   * <p>For more on 6to4 addresses see section 2 of <a target="_parent"
722   * href="http://tools.ietf.org/html/rfc3056#section-2">RFC 3056</a>.
723   *
724   * @param ip {@link Inet6Address} to be examined for 6to4 address format
725   * @return {@code true} if the argument is a 6to4 address
726   */
727  public static boolean is6to4Address(Inet6Address ip) {
728    byte[] bytes = ip.getAddress();
729    return (bytes[0] == (byte) 0x20) && (bytes[1] == (byte) 0x02);
730  }
731
732  /**
733   * Returns the IPv4 address embedded in a 6to4 address.
734   *
735   * @param ip {@link Inet6Address} to be examined for embedded IPv4 in 6to4 address
736   * @return {@link Inet4Address} of embedded IPv4 in 6to4 address
737   * @throws IllegalArgumentException if the argument is not a valid IPv6 6to4 address
738   */
739  public static Inet4Address get6to4IPv4Address(Inet6Address ip) {
740    checkArgument(is6to4Address(ip), "Address '%s' is not a 6to4 address.", toAddrString(ip));
741
742    return getInet4Address(Arrays.copyOfRange(ip.getAddress(), 2, 6));
743  }
744
745  /**
746   * A simple immutable data class to encapsulate the information to be found in a Teredo address.
747   *
748   * <p>All of the fields in this class are encoded in various portions of the IPv6 address as part
749   * of the protocol. More protocols details can be found at: <a target="_parent"
750   * href="http://en.wikipedia.org/wiki/Teredo_tunneling">http://en.wikipedia.
751   * org/wiki/Teredo_tunneling</a>.
752   *
753   * <p>The RFC can be found here: <a target="_parent" href="http://tools.ietf.org/html/rfc4380">RFC
754   * 4380</a>.
755   *
756   * @since 5.0
757   */
758  public static final class TeredoInfo {
759    private final Inet4Address server;
760    private final Inet4Address client;
761    private final int port;
762    private final int flags;
763
764    /**
765     * Constructs a TeredoInfo instance.
766     *
767     * <p>Both server and client can be {@code null}, in which case the value {@code "0.0.0.0"} will
768     * be assumed.
769     *
770     * @throws IllegalArgumentException if either of the {@code port} or the {@code flags} arguments
771     *     are out of range of an unsigned short
772     */
773    // TODO: why is this public?
774    public TeredoInfo(
775        @CheckForNull Inet4Address server, @CheckForNull Inet4Address client, int port, int flags) {
776      checkArgument(
777          (port >= 0) && (port <= 0xffff), "port '%s' is out of range (0 <= port <= 0xffff)", port);
778      checkArgument(
779          (flags >= 0) && (flags <= 0xffff),
780          "flags '%s' is out of range (0 <= flags <= 0xffff)",
781          flags);
782
783      this.server = MoreObjects.firstNonNull(server, ANY4);
784      this.client = MoreObjects.firstNonNull(client, ANY4);
785      this.port = port;
786      this.flags = flags;
787    }
788
789    public Inet4Address getServer() {
790      return server;
791    }
792
793    public Inet4Address getClient() {
794      return client;
795    }
796
797    public int getPort() {
798      return port;
799    }
800
801    public int getFlags() {
802      return flags;
803    }
804  }
805
806  /**
807   * Evaluates whether the argument is a Teredo address.
808   *
809   * <p>Teredo addresses begin with the {@code "2001::/32"} prefix.
810   *
811   * @param ip {@link Inet6Address} to be examined for Teredo address format
812   * @return {@code true} if the argument is a Teredo address
813   */
814  public static boolean isTeredoAddress(Inet6Address ip) {
815    byte[] bytes = ip.getAddress();
816    return (bytes[0] == (byte) 0x20)
817        && (bytes[1] == (byte) 0x01)
818        && (bytes[2] == 0)
819        && (bytes[3] == 0);
820  }
821
822  /**
823   * Returns the Teredo information embedded in a Teredo address.
824   *
825   * @param ip {@link Inet6Address} to be examined for embedded Teredo information
826   * @return extracted {@code TeredoInfo}
827   * @throws IllegalArgumentException if the argument is not a valid IPv6 Teredo address
828   */
829  public static TeredoInfo getTeredoInfo(Inet6Address ip) {
830    checkArgument(isTeredoAddress(ip), "Address '%s' is not a Teredo address.", toAddrString(ip));
831
832    byte[] bytes = ip.getAddress();
833    Inet4Address server = getInet4Address(Arrays.copyOfRange(bytes, 4, 8));
834
835    int flags = ByteStreams.newDataInput(bytes, 8).readShort() & 0xffff;
836
837    // Teredo obfuscates the mapped client port, per section 4 of the RFC.
838    int port = ~ByteStreams.newDataInput(bytes, 10).readShort() & 0xffff;
839
840    byte[] clientBytes = Arrays.copyOfRange(bytes, 12, 16);
841    for (int i = 0; i < clientBytes.length; i++) {
842      // Teredo obfuscates the mapped client IP, per section 4 of the RFC.
843      clientBytes[i] = (byte) ~clientBytes[i];
844    }
845    Inet4Address client = getInet4Address(clientBytes);
846
847    return new TeredoInfo(server, client, port, flags);
848  }
849
850  /**
851   * Evaluates whether the argument is an ISATAP address.
852   *
853   * <p>From RFC 5214: "ISATAP interface identifiers are constructed in Modified EUI-64 format [...]
854   * by concatenating the 24-bit IANA OUI (00-00-5E), the 8-bit hexadecimal value 0xFE, and a 32-bit
855   * IPv4 address in network byte order [...]"
856   *
857   * <p>For more on ISATAP addresses see section 6.1 of <a target="_parent"
858   * href="http://tools.ietf.org/html/rfc5214#section-6.1">RFC 5214</a>.
859   *
860   * @param ip {@link Inet6Address} to be examined for ISATAP address format
861   * @return {@code true} if the argument is an ISATAP address
862   */
863  public static boolean isIsatapAddress(Inet6Address ip) {
864
865    // If it's a Teredo address with the right port (41217, or 0xa101)
866    // which would be encoded as 0x5efe then it can't be an ISATAP address.
867    if (isTeredoAddress(ip)) {
868      return false;
869    }
870
871    byte[] bytes = ip.getAddress();
872
873    if ((bytes[8] | (byte) 0x03) != (byte) 0x03) {
874
875      // Verify that high byte of the 64 bit identifier is zero, modulo
876      // the U/L and G bits, with which we are not concerned.
877      return false;
878    }
879
880    return (bytes[9] == (byte) 0x00) && (bytes[10] == (byte) 0x5e) && (bytes[11] == (byte) 0xfe);
881  }
882
883  /**
884   * Returns the IPv4 address embedded in an ISATAP address.
885   *
886   * @param ip {@link Inet6Address} to be examined for embedded IPv4 in ISATAP address
887   * @return {@link Inet4Address} of embedded IPv4 in an ISATAP address
888   * @throws IllegalArgumentException if the argument is not a valid IPv6 ISATAP address
889   */
890  public static Inet4Address getIsatapIPv4Address(Inet6Address ip) {
891    checkArgument(isIsatapAddress(ip), "Address '%s' is not an ISATAP address.", toAddrString(ip));
892
893    return getInet4Address(Arrays.copyOfRange(ip.getAddress(), 12, 16));
894  }
895
896  /**
897   * Examines the Inet6Address to determine if it is an IPv6 address of one of the specified address
898   * types that contain an embedded IPv4 address.
899   *
900   * <p>NOTE: ISATAP addresses are explicitly excluded from this method due to their trivial
901   * spoofability. With other transition addresses spoofing involves (at least) infection of one's
902   * BGP routing table.
903   *
904   * @param ip {@link Inet6Address} to be examined for embedded IPv4 client address
905   * @return {@code true} if there is an embedded IPv4 client address
906   * @since 7.0
907   */
908  public static boolean hasEmbeddedIPv4ClientAddress(Inet6Address ip) {
909    return isCompatIPv4Address(ip) || is6to4Address(ip) || isTeredoAddress(ip);
910  }
911
912  /**
913   * Examines the Inet6Address to extract the embedded IPv4 client address if the InetAddress is an
914   * IPv6 address of one of the specified address types that contain an embedded IPv4 address.
915   *
916   * <p>NOTE: ISATAP addresses are explicitly excluded from this method due to their trivial
917   * spoofability. With other transition addresses spoofing involves (at least) infection of one's
918   * BGP routing table.
919   *
920   * @param ip {@link Inet6Address} to be examined for embedded IPv4 client address
921   * @return {@link Inet4Address} of embedded IPv4 client address
922   * @throws IllegalArgumentException if the argument does not have a valid embedded IPv4 address
923   */
924  public static Inet4Address getEmbeddedIPv4ClientAddress(Inet6Address ip) {
925    if (isCompatIPv4Address(ip)) {
926      return getCompatIPv4Address(ip);
927    }
928
929    if (is6to4Address(ip)) {
930      return get6to4IPv4Address(ip);
931    }
932
933    if (isTeredoAddress(ip)) {
934      return getTeredoInfo(ip).getClient();
935    }
936
937    throw formatIllegalArgumentException("'%s' has no embedded IPv4 address.", toAddrString(ip));
938  }
939
940  /**
941   * Evaluates whether the argument is an "IPv4 mapped" IPv6 address.
942   *
943   * <p>An "IPv4 mapped" address is anything in the range ::ffff:0:0/96 (sometimes written as
944   * ::ffff:0.0.0.0/96), with the last 32 bits interpreted as an IPv4 address.
945   *
946   * <p>For more on IPv4 mapped addresses see section 2.5.5.2 of <a target="_parent"
947   * href="http://tools.ietf.org/html/rfc4291#section-2.5.5.2">RFC 4291</a>.
948   *
949   * <p>Note: This method takes a {@code String} argument because {@link InetAddress} automatically
950   * collapses mapped addresses to IPv4. (It is actually possible to avoid this using one of the
951   * obscure {@link Inet6Address} methods, but it would be unwise to depend on such a
952   * poorly-documented feature.)
953   *
954   * <p>This method accepts non-ASCII digits. That is consistent with {@link InetAddress}, but not
955   * with various RFCs. If you want to accept ASCII digits only, you can use something like {@code
956   * CharMatcher.ascii().matchesAllOf(ipString)}.
957   *
958   * @param ipString {@code String} to be examined for embedded IPv4-mapped IPv6 address format
959   * @return {@code true} if the argument is a valid "mapped" address
960   * @since 10.0
961   */
962  public static boolean isMappedIPv4Address(String ipString) {
963    byte[] bytes = ipStringToBytes(ipString, null);
964    if (bytes != null && bytes.length == 16) {
965      for (int i = 0; i < 10; i++) {
966        if (bytes[i] != 0) {
967          return false;
968        }
969      }
970      for (int i = 10; i < 12; i++) {
971        if (bytes[i] != (byte) 0xff) {
972          return false;
973        }
974      }
975      return true;
976    }
977    return false;
978  }
979
980  /**
981   * Coerces an IPv6 address into an IPv4 address.
982   *
983   * <p>HACK: As long as applications continue to use IPv4 addresses for indexing into tables,
984   * accounting, et cetera, it may be necessary to <b>coerce</b> IPv6 addresses into IPv4 addresses.
985   * This method does so by hashing 64 bits of the IPv6 address into {@code 224.0.0.0/3} (64 bits
986   * into 29 bits):
987   *
988   * <ul>
989   *   <li>If the IPv6 address contains an embedded IPv4 address, the function hashes that.
990   *   <li>Otherwise, it hashes the upper 64 bits of the IPv6 address.
991   * </ul>
992   *
993   * <p>A "coerced" IPv4 address is equivalent to itself.
994   *
995   * <p>NOTE: This method is failsafe for security purposes: ALL IPv6 addresses (except localhost
996   * (::1)) are hashed to avoid the security risk associated with extracting an embedded IPv4
997   * address that might permit elevated privileges.
998   *
999   * @param ip {@link InetAddress} to "coerce"
1000   * @return {@link Inet4Address} represented "coerced" address
1001   * @since 7.0
1002   */
1003  public static Inet4Address getCoercedIPv4Address(InetAddress ip) {
1004    if (ip instanceof Inet4Address) {
1005      return (Inet4Address) ip;
1006    }
1007
1008    // Special cases:
1009    byte[] bytes = ip.getAddress();
1010    boolean leadingBytesOfZero = true;
1011    for (int i = 0; i < 15; ++i) {
1012      if (bytes[i] != 0) {
1013        leadingBytesOfZero = false;
1014        break;
1015      }
1016    }
1017    if (leadingBytesOfZero && (bytes[15] == 1)) {
1018      return LOOPBACK4; // ::1
1019    } else if (leadingBytesOfZero && (bytes[15] == 0)) {
1020      return ANY4; // ::0
1021    }
1022
1023    Inet6Address ip6 = (Inet6Address) ip;
1024    long addressAsLong = 0;
1025    if (hasEmbeddedIPv4ClientAddress(ip6)) {
1026      addressAsLong = getEmbeddedIPv4ClientAddress(ip6).hashCode();
1027    } else {
1028      // Just extract the high 64 bits (assuming the rest is user-modifiable).
1029      addressAsLong = ByteBuffer.wrap(ip6.getAddress(), 0, 8).getLong();
1030    }
1031
1032    // Many strategies for hashing are possible. This might suffice for now.
1033    int coercedHash = Hashing.murmur3_32_fixed().hashLong(addressAsLong).asInt();
1034
1035    // Squash into 224/4 Multicast and 240/4 Reserved space (i.e. 224/3).
1036    coercedHash |= 0xe0000000;
1037
1038    // Fixup to avoid some "illegal" values. Currently the only potential
1039    // illegal value is 255.255.255.255.
1040    if (coercedHash == 0xffffffff) {
1041      coercedHash = 0xfffffffe;
1042    }
1043
1044    return getInet4Address(Ints.toByteArray(coercedHash));
1045  }
1046
1047  /**
1048   * Returns an integer representing an IPv4 address regardless of whether the supplied argument is
1049   * an IPv4 address or not.
1050   *
1051   * <p>IPv6 addresses are <b>coerced</b> to IPv4 addresses before being converted to integers.
1052   *
1053   * <p>As long as there are applications that assume that all IP addresses are IPv4 addresses and
1054   * can therefore be converted safely to integers (for whatever purpose) this function can be used
1055   * to handle IPv6 addresses as well until the application is suitably fixed.
1056   *
1057   * <p>NOTE: an IPv6 address coerced to an IPv4 address can only be used for such purposes as
1058   * rudimentary identification or indexing into a collection of real {@link InetAddress}es. They
1059   * cannot be used as real addresses for the purposes of network communication.
1060   *
1061   * @param ip {@link InetAddress} to convert
1062   * @return {@code int}, "coerced" if ip is not an IPv4 address
1063   * @since 7.0
1064   */
1065  public static int coerceToInteger(InetAddress ip) {
1066    return ByteStreams.newDataInput(getCoercedIPv4Address(ip).getAddress()).readInt();
1067  }
1068
1069  /**
1070   * Returns a BigInteger representing the address.
1071   *
1072   * <p>Unlike {@code coerceToInteger}, IPv6 addresses are not coerced to IPv4 addresses.
1073   *
1074   * @param address {@link InetAddress} to convert
1075   * @return {@code BigInteger} representation of the address
1076   * @since 28.2
1077   */
1078  public static BigInteger toBigInteger(InetAddress address) {
1079    return new BigInteger(1, address.getAddress());
1080  }
1081
1082  /**
1083   * Returns an Inet4Address having the integer value specified by the argument.
1084   *
1085   * @param address {@code int}, the 32bit integer address to be converted
1086   * @return {@link Inet4Address} equivalent of the argument
1087   */
1088  public static Inet4Address fromInteger(int address) {
1089    return getInet4Address(Ints.toByteArray(address));
1090  }
1091
1092  /**
1093   * Returns the {@code Inet4Address} corresponding to a given {@code BigInteger}.
1094   *
1095   * @param address BigInteger representing the IPv4 address
1096   * @return Inet4Address representation of the given BigInteger
1097   * @throws IllegalArgumentException if the BigInteger is not between 0 and 2^32-1
1098   * @since 28.2
1099   */
1100  public static Inet4Address fromIPv4BigInteger(BigInteger address) {
1101    return (Inet4Address) fromBigInteger(address, false);
1102  }
1103  /**
1104   * Returns the {@code Inet6Address} corresponding to a given {@code BigInteger}.
1105   *
1106   * @param address BigInteger representing the IPv6 address
1107   * @return Inet6Address representation of the given BigInteger
1108   * @throws IllegalArgumentException if the BigInteger is not between 0 and 2^128-1
1109   * @since 28.2
1110   */
1111  public static Inet6Address fromIPv6BigInteger(BigInteger address) {
1112    return (Inet6Address) fromBigInteger(address, true);
1113  }
1114
1115  /**
1116   * Converts a BigInteger to either an IPv4 or IPv6 address. If the IP is IPv4, it must be
1117   * constrained to 32 bits, otherwise it is constrained to 128 bits.
1118   *
1119   * @param address the address represented as a big integer
1120   * @param isIpv6 whether the created address should be IPv4 or IPv6
1121   * @return the BigInteger converted to an address
1122   * @throws IllegalArgumentException if the BigInteger is not between 0 and maximum value for IPv4
1123   *     or IPv6 respectively
1124   */
1125  private static InetAddress fromBigInteger(BigInteger address, boolean isIpv6) {
1126    checkArgument(address.signum() >= 0, "BigInteger must be greater than or equal to 0");
1127
1128    int numBytes = isIpv6 ? 16 : 4;
1129
1130    byte[] addressBytes = address.toByteArray();
1131    byte[] targetCopyArray = new byte[numBytes];
1132
1133    int srcPos = max(0, addressBytes.length - numBytes);
1134    int copyLength = addressBytes.length - srcPos;
1135    int destPos = numBytes - copyLength;
1136
1137    // Check the extra bytes in the BigInteger are all zero.
1138    for (int i = 0; i < srcPos; i++) {
1139      if (addressBytes[i] != 0x00) {
1140        throw formatIllegalArgumentException(
1141            "BigInteger cannot be converted to InetAddress because it has more than %d"
1142                + " bytes: %s",
1143            numBytes, address);
1144      }
1145    }
1146
1147    // Copy the bytes into the least significant positions.
1148    System.arraycopy(addressBytes, srcPos, targetCopyArray, destPos, copyLength);
1149
1150    try {
1151      return InetAddress.getByAddress(targetCopyArray);
1152    } catch (UnknownHostException impossible) {
1153      throw new AssertionError(impossible);
1154    }
1155  }
1156
1157  /**
1158   * Returns an address from a <b>little-endian ordered</b> byte array (the opposite of what {@link
1159   * InetAddress#getByAddress} expects).
1160   *
1161   * <p>IPv4 address byte array must be 4 bytes long and IPv6 byte array must be 16 bytes long.
1162   *
1163   * @param addr the raw IP address in little-endian byte order
1164   * @return an InetAddress object created from the raw IP address
1165   * @throws UnknownHostException if IP address is of illegal length
1166   */
1167  public static InetAddress fromLittleEndianByteArray(byte[] addr) throws UnknownHostException {
1168    byte[] reversed = new byte[addr.length];
1169    for (int i = 0; i < addr.length; i++) {
1170      reversed[i] = addr[addr.length - i - 1];
1171    }
1172    return InetAddress.getByAddress(reversed);
1173  }
1174
1175  /**
1176   * Returns a new InetAddress that is one less than the passed in address. This method works for
1177   * both IPv4 and IPv6 addresses.
1178   *
1179   * @param address the InetAddress to decrement
1180   * @return a new InetAddress that is one less than the passed in address
1181   * @throws IllegalArgumentException if InetAddress is at the beginning of its range
1182   * @since 18.0
1183   */
1184  public static InetAddress decrement(InetAddress address) {
1185    byte[] addr = address.getAddress();
1186    int i = addr.length - 1;
1187    while (i >= 0 && addr[i] == (byte) 0x00) {
1188      addr[i] = (byte) 0xff;
1189      i--;
1190    }
1191
1192    checkArgument(i >= 0, "Decrementing %s would wrap.", address);
1193
1194    addr[i]--;
1195    return bytesToInetAddress(addr, null);
1196  }
1197
1198  /**
1199   * Returns a new InetAddress that is one more than the passed in address. This method works for
1200   * both IPv4 and IPv6 addresses.
1201   *
1202   * @param address the InetAddress to increment
1203   * @return a new InetAddress that is one more than the passed in address
1204   * @throws IllegalArgumentException if InetAddress is at the end of its range
1205   * @since 10.0
1206   */
1207  public static InetAddress increment(InetAddress address) {
1208    byte[] addr = address.getAddress();
1209    int i = addr.length - 1;
1210    while (i >= 0 && addr[i] == (byte) 0xff) {
1211      addr[i] = 0;
1212      i--;
1213    }
1214
1215    checkArgument(i >= 0, "Incrementing %s would wrap.", address);
1216
1217    addr[i]++;
1218    return bytesToInetAddress(addr, null);
1219  }
1220
1221  /**
1222   * Returns true if the InetAddress is either 255.255.255.255 for IPv4 or
1223   * ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6.
1224   *
1225   * @return true if the InetAddress is either 255.255.255.255 for IPv4 or
1226   *     ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6
1227   * @since 10.0
1228   */
1229  public static boolean isMaximum(InetAddress address) {
1230    byte[] addr = address.getAddress();
1231    for (byte b : addr) {
1232      if (b != (byte) 0xff) {
1233        return false;
1234      }
1235    }
1236    return true;
1237  }
1238
1239  private static IllegalArgumentException formatIllegalArgumentException(
1240      String format, Object... args) {
1241    return new IllegalArgumentException(String.format(Locale.ROOT, format, args));
1242  }
1243}