1 /* 2 * Copyright (C) 2008 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.net; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.VisibleForTesting; 21 import com.google.common.base.Preconditions; 22 import com.google.common.io.ByteStreams; 23 import com.google.common.primitives.Ints; 24 25 import java.net.Inet4Address; 26 import java.net.Inet6Address; 27 import java.net.InetAddress; 28 import java.net.UnknownHostException; 29 import java.nio.ByteBuffer; 30 import java.util.Arrays; 31 32 import javax.annotation.Nullable; 33 34 /** 35 * Static utility methods pertaining to {@link InetAddress} instances. 36 * 37 * <p><b>Important note:</b> Unlike {@code InetAddress.getByName()}, the 38 * methods of this class never cause DNS services to be accessed. For 39 * this reason, you should prefer these methods as much as possible over 40 * their JDK equivalents whenever you are expecting to handle only 41 * IP address string literals -- there is no blocking DNS penalty for a 42 * malformed string. 43 * 44 * <p>This class hooks into the {@code sun.net.util.IPAddressUtil} class 45 * to make use of the {@code textToNumericFormatV4} and 46 * {@code textToNumericFormatV6} methods directly as a means to avoid 47 * accidentally traversing all nameservices (it can be vitally important 48 * to avoid, say, blocking on DNS at times). 49 * 50 * <p>When dealing with {@link Inet4Address} and {@link Inet6Address} 51 * objects as byte arrays (vis. {@code InetAddress.getAddress()}) they 52 * are 4 and 16 bytes in length, respectively, and represent the address 53 * in network byte order. 54 * 55 * <p>Examples of IP addresses and their byte representations: 56 * <ul> 57 * <li>The IPv4 loopback address, {@code "127.0.0.1"}.<br/> 58 * {@code 7f 00 00 01} 59 * 60 * <li>The IPv6 loopback address, {@code "::1"}.<br/> 61 * {@code 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01} 62 * 63 * <li>From the IPv6 reserved documentation prefix ({@code 2001:db8::/32}), 64 * {@code "2001:db8::1"}.<br/> 65 * {@code 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01} 66 * 67 * <li>An IPv6 "IPv4 compatible" (or "compat") address, 68 * {@code "::192.168.0.1"}.<br/> 69 * {@code 00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01} 70 * 71 * <li>An IPv6 "IPv4 mapped" address, {@code "::ffff:192.168.0.1"}.<br/> 72 * {@code 00 00 00 00 00 00 00 00 00 00 ff ff c0 a8 00 01} 73 * </ul> 74 * 75 * <p>A few notes about IPv6 "IPv4 mapped" addresses and their observed 76 * use in Java. 77 * <br><br> 78 * "IPv4 mapped" addresses were originally a representation of IPv4 79 * addresses for use on an IPv6 socket that could receive both IPv4 80 * and IPv6 connections (by disabling the {@code IPV6_V6ONLY} socket 81 * option on an IPv6 socket). Yes, it's confusing. Nevertheless, 82 * these "mapped" addresses were never supposed to be seen on the 83 * wire. That assumption was dropped, some say mistakenly, in later 84 * RFCs with the apparent aim of making IPv4-to-IPv6 transition simpler. 85 * 86 * <p>Technically one <i>can</i> create a 128bit IPv6 address with the wire 87 * format of a "mapped" address, as shown above, and transmit it in an 88 * IPv6 packet header. However, Java's InetAddress creation methods 89 * appear to adhere doggedly to the original intent of the "mapped" 90 * address: all "mapped" addresses return {@link Inet4Address} objects. 91 * 92 * <p>For added safety, it is common for IPv6 network operators to filter 93 * all packets where either the source or destination address appears to 94 * be a "compat" or "mapped" address. Filtering suggestions usually 95 * recommend discarding any packets with source or destination addresses 96 * in the invalid range {@code ::/3}, which includes both of these bizarre 97 * address formats. For more information on "bogons", including lists 98 * of IPv6 bogon space, see: 99 * 100 * <ul> 101 * <li><a target="_parent" 102 * href="http://en.wikipedia.org/wiki/Bogon_filtering" 103 * >http://en.wikipedia.org/wiki/Bogon_filtering</a> 104 * <li><a target="_parent" 105 * href="http://www.cymru.com/Bogons/ipv6.txt" 106 * >http://www.cymru.com/Bogons/ipv6.txt</a> 107 * <li><a target="_parent" 108 * href="http://www.cymru.com/Bogons/v6bogon.html" 109 * >http://www.cymru.com/Bogons/v6bogon.html</a> 110 * <li><a target="_parent" 111 * href="http://www.space.net/~gert/RIPE/ipv6-filters.html" 112 * >http://www.space.net/~gert/RIPE/ipv6-filters.html</a> 113 * </ul> 114 * 115 * @author Erik Kline 116 * @since 5.0 117 */ 118 @Beta 119 public final class InetAddresses { 120 private static final int IPV4_PART_COUNT = 4; 121 private static final int IPV6_PART_COUNT = 8; 122 private static final Inet4Address LOOPBACK4 = 123 (Inet4Address) forString("127.0.0.1"); 124 private static final Inet4Address ANY4 = 125 (Inet4Address) forString("0.0.0.0"); 126 InetAddresses()127 private InetAddresses() {} 128 129 /** 130 * Returns an {@link Inet4Address}, given a byte array representation 131 * of the IPv4 address. 132 * 133 * @param bytes byte array representing an IPv4 address (should be 134 * of length 4). 135 * @return {@link Inet4Address} corresponding to the supplied byte 136 * array. 137 * @throws IllegalArgumentException if a valid {@link Inet4Address} 138 * can not be created. 139 */ getInet4Address(byte[] bytes)140 private static Inet4Address getInet4Address(byte[] bytes) { 141 Preconditions.checkArgument(bytes.length == 4, 142 "Byte array has invalid length for an IPv4 address: %s != 4.", 143 bytes.length); 144 145 try { 146 InetAddress ipv4 = InetAddress.getByAddress(bytes); 147 if (!(ipv4 instanceof Inet4Address)) { 148 throw new UnknownHostException( 149 String.format("'%s' is not an IPv4 address.", 150 ipv4.getHostAddress())); 151 } 152 153 return (Inet4Address) ipv4; 154 } catch (UnknownHostException e) { 155 156 /* 157 * This really shouldn't happen in practice since all our byte 158 * sequences should be valid IP addresses. 159 * 160 * However {@link InetAddress#getByAddress} is documented as 161 * potentially throwing this "if IP address is of illegal length". 162 * 163 * This is mapped to IllegalArgumentException since, presumably, 164 * the argument triggered some bizarre processing bug. 165 */ 166 throw new IllegalArgumentException( 167 String.format("Host address '%s' is not a valid IPv4 address.", 168 Arrays.toString(bytes)), 169 e); 170 } 171 } 172 173 /** 174 * Returns the {@link InetAddress} having the given string 175 * representation. 176 * 177 * <p>This deliberately avoids all nameservice lookups (e.g. no DNS). 178 * 179 * @param ipString {@code String} containing an IPv4 or IPv6 string literal, 180 * e.g. {@code "192.168.0.1"} or {@code "2001:db8::1"} 181 * @return {@link InetAddress} representing the argument 182 * @throws IllegalArgumentException if the argument is not a valid 183 * IP string literal 184 */ forString(String ipString)185 public static InetAddress forString(String ipString) { 186 byte[] addr = ipStringToBytes(ipString); 187 188 // The argument was malformed, i.e. not an IP string literal. 189 if (addr == null) { 190 throw new IllegalArgumentException( 191 String.format("'%s' is not an IP string literal.", ipString)); 192 } 193 194 try { 195 return InetAddress.getByAddress(addr); 196 } catch (UnknownHostException e) { 197 198 /* 199 * This really shouldn't happen in practice since all our byte 200 * sequences should be valid IP addresses. 201 * 202 * However {@link InetAddress#getByAddress} is documented as 203 * potentially throwing this "if IP address is of illegal length". 204 * 205 * This is mapped to IllegalArgumentException since, presumably, 206 * the argument triggered some processing bug in either 207 * {@link IPAddressUtil#textToNumericFormatV4} or 208 * {@link IPAddressUtil#textToNumericFormatV6}. 209 */ 210 throw new IllegalArgumentException( 211 String.format("'%s' is extremely broken.", ipString), e); 212 } 213 } 214 215 /** 216 * Returns {@code true} if the supplied string is a valid IP string 217 * literal, {@code false} otherwise. 218 * 219 * @param ipString {@code String} to evaluated as an IP string literal 220 * @return {@code true} if the argument is a valid IP string literal 221 */ isInetAddress(String ipString)222 public static boolean isInetAddress(String ipString) { 223 return ipStringToBytes(ipString) != null; 224 } 225 ipStringToBytes(String ipString)226 private static byte[] ipStringToBytes(String ipString) { 227 // Make a first pass to categorize the characters in this string. 228 boolean hasColon = false; 229 boolean hasDot = false; 230 for (int i = 0; i < ipString.length(); i++) { 231 char c = ipString.charAt(i); 232 if (c == '.') { 233 hasDot = true; 234 } else if (c == ':') { 235 if (hasDot) { 236 return null; // Colons must not appear after dots. 237 } 238 hasColon = true; 239 } else if (Character.digit(c, 16) == -1) { 240 return null; // Everything else must be a decimal or hex digit. 241 } 242 } 243 244 // Now decide which address family to parse. 245 if (hasColon) { 246 if (hasDot) { 247 ipString = convertDottedQuadToHex(ipString); 248 if (ipString == null) { 249 return null; 250 } 251 } 252 return textToNumericFormatV6(ipString); 253 } else if (hasDot) { 254 return textToNumericFormatV4(ipString); 255 } 256 return null; 257 } 258 textToNumericFormatV4(String ipString)259 private static byte[] textToNumericFormatV4(String ipString) { 260 String[] address = ipString.split("\\.", IPV4_PART_COUNT + 1); 261 if (address.length != IPV4_PART_COUNT) { 262 return null; 263 } 264 265 byte[] bytes = new byte[IPV4_PART_COUNT]; 266 try { 267 for (int i = 0; i < bytes.length; i++) { 268 bytes[i] = parseOctet(address[i]); 269 } 270 } catch (NumberFormatException ex) { 271 return null; 272 } 273 274 return bytes; 275 } 276 textToNumericFormatV6(String ipString)277 private static byte[] textToNumericFormatV6(String ipString) { 278 // An address can have [2..8] colons, and N colons make N+1 parts. 279 String[] parts = ipString.split(":", IPV6_PART_COUNT + 2); 280 if (parts.length < 3 || parts.length > IPV6_PART_COUNT + 1) { 281 return null; 282 } 283 284 // Disregarding the endpoints, find "::" with nothing in between. 285 // This indicates that a run of zeroes has been skipped. 286 int skipIndex = -1; 287 for (int i = 1; i < parts.length - 1; i++) { 288 if (parts[i].length() == 0) { 289 if (skipIndex >= 0) { 290 return null; // Can't have more than one :: 291 } 292 skipIndex = i; 293 } 294 } 295 296 int partsHi; // Number of parts to copy from above/before the "::" 297 int partsLo; // Number of parts to copy from below/after the "::" 298 if (skipIndex >= 0) { 299 // If we found a "::", then check if it also covers the endpoints. 300 partsHi = skipIndex; 301 partsLo = parts.length - skipIndex - 1; 302 if (parts[0].length() == 0 && --partsHi != 0) { 303 return null; // ^: requires ^:: 304 } 305 if (parts[parts.length - 1].length() == 0 && --partsLo != 0) { 306 return null; // :$ requires ::$ 307 } 308 } else { 309 // Otherwise, allocate the entire address to partsHi. The endpoints 310 // could still be empty, but parseHextet() will check for that. 311 partsHi = parts.length; 312 partsLo = 0; 313 } 314 315 // If we found a ::, then we must have skipped at least one part. 316 // Otherwise, we must have exactly the right number of parts. 317 int partsSkipped = IPV6_PART_COUNT - (partsHi + partsLo); 318 if (!(skipIndex >= 0 ? partsSkipped >= 1 : partsSkipped == 0)) { 319 return null; 320 } 321 322 // Now parse the hextets into a byte array. 323 ByteBuffer rawBytes = ByteBuffer.allocate(2 * IPV6_PART_COUNT); 324 try { 325 for (int i = 0; i < partsHi; i++) { 326 rawBytes.putShort(parseHextet(parts[i])); 327 } 328 for (int i = 0; i < partsSkipped; i++) { 329 rawBytes.putShort((short) 0); 330 } 331 for (int i = partsLo; i > 0; i--) { 332 rawBytes.putShort(parseHextet(parts[parts.length - i])); 333 } 334 } catch (NumberFormatException ex) { 335 return null; 336 } 337 return rawBytes.array(); 338 } 339 convertDottedQuadToHex(String ipString)340 private static String convertDottedQuadToHex(String ipString) { 341 int lastColon = ipString.lastIndexOf(':'); 342 String initialPart = ipString.substring(0, lastColon + 1); 343 String dottedQuad = ipString.substring(lastColon + 1); 344 byte[] quad = textToNumericFormatV4(dottedQuad); 345 if (quad == null) { 346 return null; 347 } 348 String penultimate = Integer.toHexString(((quad[0] & 0xff) << 8) | (quad[1] & 0xff)); 349 String ultimate = Integer.toHexString(((quad[2] & 0xff) << 8) | (quad[3] & 0xff)); 350 return initialPart + penultimate + ":" + ultimate; 351 } 352 parseOctet(String ipPart)353 private static byte parseOctet(String ipPart) { 354 // Note: we already verified that this string contains only hex digits. 355 int octet = Integer.parseInt(ipPart); 356 // Disallow leading zeroes, because no clear standard exists on 357 // whether these should be interpreted as decimal or octal. 358 if (octet > 255 || (ipPart.startsWith("0") && ipPart.length() > 1)) { 359 throw new NumberFormatException(); 360 } 361 return (byte) octet; 362 } 363 parseHextet(String ipPart)364 private static short parseHextet(String ipPart) { 365 // Note: we already verified that this string contains only hex digits. 366 int hextet = Integer.parseInt(ipPart, 16); 367 if (hextet > 0xffff) { 368 throw new NumberFormatException(); 369 } 370 return (short) hextet; 371 } 372 373 /** 374 * Returns the string representation of an {@link InetAddress}. 375 * 376 * <p>For IPv4 addresses, this is identical to 377 * {@link InetAddress#getHostAddress()}, but for IPv6 addresses, the output 378 * follows <a href="http://tools.ietf.org/html/rfc5952">RFC 5952</a> 379 * section 4. The main difference is that this method uses "::" for zero 380 * compression, while Java's version uses the uncompressed form. 381 * 382 * <p>This method uses hexadecimal for all IPv6 addresses, including 383 * IPv4-mapped IPv6 addresses such as "::c000:201". The output does not 384 * include a Scope ID. 385 * 386 * @param ip {@link InetAddress} to be converted to an address string 387 * @return {@code String} containing the text-formatted IP address 388 * @since 10.0 389 */ toAddrString(InetAddress ip)390 public static String toAddrString(InetAddress ip) { 391 Preconditions.checkNotNull(ip); 392 if (ip instanceof Inet4Address) { 393 // For IPv4, Java's formatting is good enough. 394 return ip.getHostAddress(); 395 } 396 Preconditions.checkArgument(ip instanceof Inet6Address); 397 byte[] bytes = ip.getAddress(); 398 int[] hextets = new int[IPV6_PART_COUNT]; 399 for (int i = 0; i < hextets.length; i++) { 400 hextets[i] = Ints.fromBytes( 401 (byte) 0, (byte) 0, bytes[2 * i], bytes[2 * i + 1]); 402 } 403 compressLongestRunOfZeroes(hextets); 404 return hextetsToIPv6String(hextets); 405 } 406 407 /** 408 * Identify and mark the longest run of zeroes in an IPv6 address. 409 * 410 * <p>Only runs of two or more hextets are considered. In case of a tie, the 411 * leftmost run wins. If a qualifying run is found, its hextets are replaced 412 * by the sentinel value -1. 413 * 414 * @param hextets {@code int[]} mutable array of eight 16-bit hextets. 415 */ compressLongestRunOfZeroes(int[] hextets)416 private static void compressLongestRunOfZeroes(int[] hextets) { 417 int bestRunStart = -1; 418 int bestRunLength = -1; 419 int runStart = -1; 420 for (int i = 0; i < hextets.length + 1; i++) { 421 if (i < hextets.length && hextets[i] == 0) { 422 if (runStart < 0) { 423 runStart = i; 424 } 425 } else if (runStart >= 0) { 426 int runLength = i - runStart; 427 if (runLength > bestRunLength) { 428 bestRunStart = runStart; 429 bestRunLength = runLength; 430 } 431 runStart = -1; 432 } 433 } 434 if (bestRunLength >= 2) { 435 Arrays.fill(hextets, bestRunStart, bestRunStart + bestRunLength, -1); 436 } 437 } 438 439 /** 440 * Convert a list of hextets into a human-readable IPv6 address. 441 * 442 * <p>In order for "::" compression to work, the input should contain negative 443 * sentinel values in place of the elided zeroes. 444 * 445 * @param hextets {@code int[]} array of eight 16-bit hextets, or -1s. 446 */ hextetsToIPv6String(int[] hextets)447 private static String hextetsToIPv6String(int[] hextets) { 448 /* 449 * While scanning the array, handle these state transitions: 450 * start->num => "num" start->gap => "::" 451 * num->num => ":num" num->gap => "::" 452 * gap->num => "num" gap->gap => "" 453 */ 454 StringBuilder buf = new StringBuilder(39); 455 boolean lastWasNumber = false; 456 for (int i = 0; i < hextets.length; i++) { 457 boolean thisIsNumber = hextets[i] >= 0; 458 if (thisIsNumber) { 459 if (lastWasNumber) { 460 buf.append(':'); 461 } 462 buf.append(Integer.toHexString(hextets[i])); 463 } else { 464 if (i == 0 || lastWasNumber) { 465 buf.append("::"); 466 } 467 } 468 lastWasNumber = thisIsNumber; 469 } 470 return buf.toString(); 471 } 472 473 /** 474 * Returns the string representation of an {@link InetAddress} suitable 475 * for inclusion in a URI. 476 * 477 * <p>For IPv4 addresses, this is identical to 478 * {@link InetAddress#getHostAddress()}, but for IPv6 addresses it 479 * compresses zeroes and surrounds the text with square brackets; for example 480 * {@code "[2001:db8::1]"}. 481 * 482 * <p>Per section 3.2.2 of 483 * <a target="_parent" 484 * href="http://tools.ietf.org/html/rfc3986#section-3.2.2" 485 * >http://tools.ietf.org/html/rfc3986</a>, 486 * a URI containing an IPv6 string literal is of the form 487 * {@code "http://[2001:db8::1]:8888/index.html"}. 488 * 489 * <p>Use of either {@link InetAddresses#toAddrString}, 490 * {@link InetAddress#getHostAddress()}, or this method is recommended over 491 * {@link InetAddress#toString()} when an IP address string literal is 492 * desired. This is because {@link InetAddress#toString()} prints the 493 * hostname and the IP address string joined by a "/". 494 * 495 * @param ip {@link InetAddress} to be converted to URI string literal 496 * @return {@code String} containing URI-safe string literal 497 */ toUriString(InetAddress ip)498 public static String toUriString(InetAddress ip) { 499 if (ip instanceof Inet6Address) { 500 return "[" + toAddrString(ip) + "]"; 501 } 502 return toAddrString(ip); 503 } 504 505 /** 506 * Returns an InetAddress representing the literal IPv4 or IPv6 host 507 * portion of a URL, encoded in the format specified by RFC 3986 section 3.2.2. 508 * 509 * <p>This function is similar to {@link InetAddresses#forString(String)}, 510 * however, it requires that IPv6 addresses are surrounded by square brackets. 511 * 512 * <p>This function is the inverse of 513 * {@link InetAddresses#toUriString(java.net.InetAddress)}. 514 * 515 * @param hostAddr A RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address 516 * @return an InetAddress representing the address in {@code hostAddr} 517 * @throws IllegalArgumentException if {@code hostAddr} is not a valid 518 * IPv4 address, or IPv6 address surrounded by square brackets 519 */ forUriString(String hostAddr)520 public static InetAddress forUriString(String hostAddr) { 521 Preconditions.checkNotNull(hostAddr); 522 Preconditions.checkArgument(hostAddr.length() > 0, "host string is empty"); 523 InetAddress retval = null; 524 525 // IPv4 address? 526 try { 527 retval = forString(hostAddr); 528 if (retval instanceof Inet4Address) { 529 return retval; 530 } 531 } catch (IllegalArgumentException e) { 532 // Not a valid IP address, fall through. 533 } 534 535 // IPv6 address 536 if (!(hostAddr.startsWith("[") && hostAddr.endsWith("]"))) { 537 throw new IllegalArgumentException("Not a valid address: \"" + hostAddr + '"'); 538 } 539 540 retval = forString(hostAddr.substring(1, hostAddr.length() - 1)); 541 if (retval instanceof Inet6Address) { 542 return retval; 543 } 544 545 throw new IllegalArgumentException("Not a valid address: \"" + hostAddr + '"'); 546 } 547 548 /** 549 * Returns {@code true} if the supplied string is a valid URI IP string 550 * literal, {@code false} otherwise. 551 * 552 * @param ipString {@code String} to evaluated as an IP URI host string literal 553 * @return {@code true} if the argument is a valid IP URI host 554 */ isUriInetAddress(String ipString)555 public static boolean isUriInetAddress(String ipString) { 556 try { 557 forUriString(ipString); 558 return true; 559 } catch (IllegalArgumentException e) { 560 return false; 561 } 562 } 563 564 /** 565 * Evaluates whether the argument is an IPv6 "compat" address. 566 * 567 * <p>An "IPv4 compatible", or "compat", address is one with 96 leading 568 * bits of zero, with the remaining 32 bits interpreted as an 569 * IPv4 address. These are conventionally represented in string 570 * literals as {@code "::192.168.0.1"}, though {@code "::c0a8:1"} is 571 * also considered an IPv4 compatible address (and equivalent to 572 * {@code "::192.168.0.1"}). 573 * 574 * <p>For more on IPv4 compatible addresses see section 2.5.5.1 of 575 * <a target="_parent" 576 * href="http://tools.ietf.org/html/rfc4291#section-2.5.5.1" 577 * >http://tools.ietf.org/html/rfc4291</a> 578 * 579 * <p>NOTE: This method is different from 580 * {@link Inet6Address#isIPv4CompatibleAddress} in that it more 581 * correctly classifies {@code "::"} and {@code "::1"} as 582 * proper IPv6 addresses (which they are), NOT IPv4 compatible 583 * addresses (which they are generally NOT considered to be). 584 * 585 * @param ip {@link Inet6Address} to be examined for embedded IPv4 586 * compatible address format 587 * @return {@code true} if the argument is a valid "compat" address 588 */ isCompatIPv4Address(Inet6Address ip)589 public static boolean isCompatIPv4Address(Inet6Address ip) { 590 if (!ip.isIPv4CompatibleAddress()) { 591 return false; 592 } 593 594 byte[] bytes = ip.getAddress(); 595 if ((bytes[12] == 0) && (bytes[13] == 0) && (bytes[14] == 0) 596 && ((bytes[15] == 0) || (bytes[15] == 1))) { 597 return false; 598 } 599 600 return true; 601 } 602 603 /** 604 * Returns the IPv4 address embedded in an IPv4 compatible address. 605 * 606 * @param ip {@link Inet6Address} to be examined for an embedded 607 * IPv4 address 608 * @return {@link Inet4Address} of the embedded IPv4 address 609 * @throws IllegalArgumentException if the argument is not a valid 610 * IPv4 compatible address 611 */ getCompatIPv4Address(Inet6Address ip)612 public static Inet4Address getCompatIPv4Address(Inet6Address ip) { 613 Preconditions.checkArgument(isCompatIPv4Address(ip), 614 "Address '%s' is not IPv4-compatible.", toAddrString(ip)); 615 616 return getInet4Address(copyOfRange(ip.getAddress(), 12, 16)); 617 } 618 619 /** 620 * Evaluates whether the argument is a 6to4 address. 621 * 622 * <p>6to4 addresses begin with the {@code "2002::/16"} prefix. 623 * The next 32 bits are the IPv4 address of the host to which 624 * IPv6-in-IPv4 tunneled packets should be routed. 625 * 626 * <p>For more on 6to4 addresses see section 2 of 627 * <a target="_parent" href="http://tools.ietf.org/html/rfc3056#section-2" 628 * >http://tools.ietf.org/html/rfc3056</a> 629 * 630 * @param ip {@link Inet6Address} to be examined for 6to4 address 631 * format 632 * @return {@code true} if the argument is a 6to4 address 633 */ is6to4Address(Inet6Address ip)634 public static boolean is6to4Address(Inet6Address ip) { 635 byte[] bytes = ip.getAddress(); 636 return (bytes[0] == (byte) 0x20) && (bytes[1] == (byte) 0x02); 637 } 638 639 /** 640 * Returns the IPv4 address embedded in a 6to4 address. 641 * 642 * @param ip {@link Inet6Address} to be examined for embedded IPv4 643 * in 6to4 address. 644 * @return {@link Inet4Address} of embedded IPv4 in 6to4 address. 645 * @throws IllegalArgumentException if the argument is not a valid 646 * IPv6 6to4 address. 647 */ get6to4IPv4Address(Inet6Address ip)648 public static Inet4Address get6to4IPv4Address(Inet6Address ip) { 649 Preconditions.checkArgument(is6to4Address(ip), 650 "Address '%s' is not a 6to4 address.", toAddrString(ip)); 651 652 return getInet4Address(copyOfRange(ip.getAddress(), 2, 6)); 653 } 654 655 /** 656 * A simple data class to encapsulate the information to be found in a 657 * Teredo address. 658 * 659 * <p>All of the fields in this class are encoded in various portions 660 * of the IPv6 address as part of the protocol. More protocols details 661 * can be found at: 662 * <a target="_parent" href="http://en.wikipedia.org/wiki/Teredo_tunneling" 663 * >http://en.wikipedia.org/wiki/Teredo_tunneling</a>. 664 * 665 * <p>The RFC can be found here: 666 * <a target="_parent" href="http://tools.ietf.org/html/rfc4380" 667 * >http://tools.ietf.org/html/rfc4380</a>. 668 * 669 * @since 5.0 670 */ 671 @Beta 672 public static final class TeredoInfo { 673 private final Inet4Address server; 674 private final Inet4Address client; 675 private final int port; 676 private final int flags; 677 678 /** 679 * Constructs a TeredoInfo instance. 680 * 681 * <p>Both server and client can be {@code null}, in which case the 682 * value {@code "0.0.0.0"} will be assumed. 683 * 684 * @throws IllegalArgumentException if either of the {@code port} 685 * or the {@code flags} arguments are out of range of an 686 * unsigned short 687 */ 688 // TODO: why is this public? TeredoInfo(@ullable Inet4Address server, @Nullable Inet4Address client, int port, int flags)689 public TeredoInfo(@Nullable Inet4Address server, 690 @Nullable Inet4Address client, 691 int port, int flags) { 692 Preconditions.checkArgument((port >= 0) && (port <= 0xffff), 693 "port '%s' is out of range (0 <= port <= 0xffff)", port); 694 Preconditions.checkArgument((flags >= 0) && (flags <= 0xffff), 695 "flags '%s' is out of range (0 <= flags <= 0xffff)", flags); 696 697 if (server != null) { 698 this.server = server; 699 } else { 700 this.server = ANY4; 701 } 702 703 if (client != null) { 704 this.client = client; 705 } else { 706 this.client = ANY4; 707 } 708 709 this.port = port; 710 this.flags = flags; 711 } 712 getServer()713 public Inet4Address getServer() { 714 return server; 715 } 716 getClient()717 public Inet4Address getClient() { 718 return client; 719 } 720 getPort()721 public int getPort() { 722 return port; 723 } 724 getFlags()725 public int getFlags() { 726 return flags; 727 } 728 } 729 730 /** 731 * Evaluates whether the argument is a Teredo address. 732 * 733 * <p>Teredo addresses begin with the {@code "2001::/32"} prefix. 734 * 735 * @param ip {@link Inet6Address} to be examined for Teredo address 736 * format. 737 * @return {@code true} if the argument is a Teredo address 738 */ isTeredoAddress(Inet6Address ip)739 public static boolean isTeredoAddress(Inet6Address ip) { 740 byte[] bytes = ip.getAddress(); 741 return (bytes[0] == (byte) 0x20) && (bytes[1] == (byte) 0x01) 742 && (bytes[2] == 0) && (bytes[3] == 0); 743 } 744 745 /** 746 * Returns the Teredo information embedded in a Teredo address. 747 * 748 * @param ip {@link Inet6Address} to be examined for embedded Teredo 749 * information 750 * @return extracted {@code TeredoInfo} 751 * @throws IllegalArgumentException if the argument is not a valid 752 * IPv6 Teredo address 753 */ getTeredoInfo(Inet6Address ip)754 public static TeredoInfo getTeredoInfo(Inet6Address ip) { 755 Preconditions.checkArgument(isTeredoAddress(ip), 756 "Address '%s' is not a Teredo address.", toAddrString(ip)); 757 758 byte[] bytes = ip.getAddress(); 759 Inet4Address server = getInet4Address(copyOfRange(bytes, 4, 8)); 760 761 int flags = ByteStreams.newDataInput(bytes, 8).readShort() & 0xffff; 762 763 // Teredo obfuscates the mapped client port, per section 4 of the RFC. 764 int port = ~ByteStreams.newDataInput(bytes, 10).readShort() & 0xffff; 765 766 byte[] clientBytes = copyOfRange(bytes, 12, 16); 767 for (int i = 0; i < clientBytes.length; i++) { 768 // Teredo obfuscates the mapped client IP, per section 4 of the RFC. 769 clientBytes[i] = (byte) ~clientBytes[i]; 770 } 771 Inet4Address client = getInet4Address(clientBytes); 772 773 return new TeredoInfo(server, client, port, flags); 774 } 775 776 /** 777 * Evaluates whether the argument is an ISATAP address. 778 * 779 * <p>From RFC 5214: "ISATAP interface identifiers are constructed in 780 * Modified EUI-64 format [...] by concatenating the 24-bit IANA OUI 781 * (00-00-5E), the 8-bit hexadecimal value 0xFE, and a 32-bit IPv4 782 * address in network byte order [...]" 783 * 784 * <p>For more on ISATAP addresses see section 6.1 of 785 * <a target="_parent" href="http://tools.ietf.org/html/rfc5214#section-6.1" 786 * >http://tools.ietf.org/html/rfc5214</a> 787 * 788 * @param ip {@link Inet6Address} to be examined for ISATAP address 789 * format. 790 * @return {@code true} if the argument is an ISATAP address 791 */ isIsatapAddress(Inet6Address ip)792 public static boolean isIsatapAddress(Inet6Address ip) { 793 794 // If it's a Teredo address with the right port (41217, or 0xa101) 795 // which would be encoded as 0x5efe then it can't be an ISATAP address. 796 if (isTeredoAddress(ip)) { 797 return false; 798 } 799 800 byte[] bytes = ip.getAddress(); 801 802 if ((bytes[8] | (byte) 0x03) != (byte) 0x03) { 803 804 // Verify that high byte of the 64 bit identifier is zero, modulo 805 // the U/L and G bits, with which we are not concerned. 806 return false; 807 } 808 809 return (bytes[9] == (byte) 0x00) && (bytes[10] == (byte) 0x5e) 810 && (bytes[11] == (byte) 0xfe); 811 } 812 813 /** 814 * Returns the IPv4 address embedded in an ISATAP address. 815 * 816 * @param ip {@link Inet6Address} to be examined for embedded IPv4 817 * in ISATAP address 818 * @return {@link Inet4Address} of embedded IPv4 in an ISATAP address 819 * @throws IllegalArgumentException if the argument is not a valid 820 * IPv6 ISATAP address 821 */ getIsatapIPv4Address(Inet6Address ip)822 public static Inet4Address getIsatapIPv4Address(Inet6Address ip) { 823 Preconditions.checkArgument(isIsatapAddress(ip), 824 "Address '%s' is not an ISATAP address.", toAddrString(ip)); 825 826 return getInet4Address(copyOfRange(ip.getAddress(), 12, 16)); 827 } 828 829 /** 830 * Examines the Inet6Address to determine if it is an IPv6 address of one 831 * of the specified address types that contain an embedded IPv4 address. 832 * 833 * <p>NOTE: ISATAP addresses are explicitly excluded from this method 834 * due to their trivial spoofability. With other transition addresses 835 * spoofing involves (at least) infection of one's BGP routing table. 836 * 837 * @param ip {@link Inet6Address} to be examined for embedded IPv4 838 * client address. 839 * @return {@code true} if there is an embedded IPv4 client address. 840 * @since 7.0 841 */ hasEmbeddedIPv4ClientAddress(Inet6Address ip)842 public static boolean hasEmbeddedIPv4ClientAddress(Inet6Address ip) { 843 return isCompatIPv4Address(ip) || is6to4Address(ip) || 844 isTeredoAddress(ip); 845 } 846 847 /** 848 * Examines the Inet6Address to extract the embedded IPv4 client address 849 * if the InetAddress is an IPv6 address of one of the specified address 850 * types that contain an embedded IPv4 address. 851 * 852 * <p>NOTE: ISATAP addresses are explicitly excluded from this method 853 * due to their trivial spoofability. With other transition addresses 854 * spoofing involves (at least) infection of one's BGP routing table. 855 * 856 * @param ip {@link Inet6Address} to be examined for embedded IPv4 857 * client address. 858 * @return {@link Inet4Address} of embedded IPv4 client address. 859 * @throws IllegalArgumentException if the argument does not have a valid 860 * embedded IPv4 address. 861 */ getEmbeddedIPv4ClientAddress(Inet6Address ip)862 public static Inet4Address getEmbeddedIPv4ClientAddress(Inet6Address ip) { 863 if (isCompatIPv4Address(ip)) { 864 return getCompatIPv4Address(ip); 865 } 866 867 if (is6to4Address(ip)) { 868 return get6to4IPv4Address(ip); 869 } 870 871 if (isTeredoAddress(ip)) { 872 return getTeredoInfo(ip).getClient(); 873 } 874 875 throw new IllegalArgumentException( 876 String.format("'%s' has no embedded IPv4 address.", 877 toAddrString(ip))); 878 } 879 880 /** 881 * Evaluates whether the argument is an "IPv4 mapped" IPv6 address. 882 * 883 * <p>An "IPv4 mapped" address is anything in the range ::ffff:0:0/96 884 * (sometimes written as ::ffff:0.0.0.0/96), with the last 32 bits 885 * interpreted as an IPv4 address. 886 * 887 * <p>For more on IPv4 mapped addresses see section 2.5.5.2 of 888 * <a target="_parent" 889 * href="http://tools.ietf.org/html/rfc4291#section-2.5.5.2" 890 * >http://tools.ietf.org/html/rfc4291</a> 891 * 892 * <p>Note: This method takes a {@code String} argument because 893 * {@link InetAddress} automatically collapses mapped addresses to IPv4. 894 * (It is actually possible to avoid this using one of the obscure 895 * {@link Inet6Address} methods, but it would be unwise to depend on such 896 * a poorly-documented feature.) 897 * 898 * @param ipString {@code String} to be examined for embedded IPv4-mapped 899 * IPv6 address format 900 * @return {@code true} if the argument is a valid "mapped" address 901 * @since 10.0 902 */ isMappedIPv4Address(String ipString)903 public static boolean isMappedIPv4Address(String ipString) { 904 byte[] bytes = ipStringToBytes(ipString); 905 if (bytes != null && bytes.length == 16) { 906 for (int i = 0; i < 10; i++) { 907 if (bytes[i] != 0) { 908 return false; 909 } 910 } 911 for (int i = 10; i < 12; i++) { 912 if (bytes[i] != (byte) 0xff) { 913 return false; 914 } 915 } 916 return true; 917 } 918 return false; 919 } 920 921 /** 922 * Coerces an IPv6 address into an IPv4 address. 923 * 924 * <p>HACK: As long as applications continue to use IPv4 addresses for 925 * indexing into tables, accounting, et cetera, it may be necessary to 926 * <b>coerce</b> IPv6 addresses into IPv4 addresses. This function does 927 * so by hashing the upper 64 bits into {@code 224.0.0.0/3} 928 * (64 bits into 29 bits). 929 * 930 * <p>A "coerced" IPv4 address is equivalent to itself. 931 * 932 * <p>NOTE: This function is failsafe for security purposes: ALL IPv6 933 * addresses (except localhost (::1)) are hashed to avoid the security 934 * risk associated with extracting an embedded IPv4 address that might 935 * permit elevated privileges. 936 * 937 * @param ip {@link InetAddress} to "coerce" 938 * @return {@link Inet4Address} represented "coerced" address 939 * @since 7.0 940 */ getCoercedIPv4Address(InetAddress ip)941 public static Inet4Address getCoercedIPv4Address(InetAddress ip) { 942 if (ip instanceof Inet4Address) { 943 return (Inet4Address) ip; 944 } 945 946 // Special cases: 947 byte[] bytes = ip.getAddress(); 948 boolean leadingBytesOfZero = true; 949 for (int i = 0; i < 15; ++i) { 950 if (bytes[i] != 0) { 951 leadingBytesOfZero = false; 952 break; 953 } 954 } 955 if (leadingBytesOfZero && (bytes[15] == 1)) { 956 return LOOPBACK4; // ::1 957 } else if (leadingBytesOfZero && (bytes[15] == 0)) { 958 return ANY4; // ::0 959 } 960 961 Inet6Address ip6 = (Inet6Address) ip; 962 long addressAsLong = 0; 963 if (hasEmbeddedIPv4ClientAddress(ip6)) { 964 addressAsLong = getEmbeddedIPv4ClientAddress(ip6).hashCode(); 965 } else { 966 967 // Just extract the high 64 bits (assuming the rest is user-modifiable). 968 addressAsLong = ByteBuffer.wrap(ip6.getAddress(), 0, 8).getLong(); 969 } 970 971 // Many strategies for hashing are possible. This might suffice for now. 972 int coercedHash = hash64To32(addressAsLong); 973 974 // Squash into 224/4 Multicast and 240/4 Reserved space (i.e. 224/3). 975 coercedHash |= 0xe0000000; 976 977 // Fixup to avoid some "illegal" values. Currently the only potential 978 // illegal value is 255.255.255.255. 979 if (coercedHash == 0xffffffff) { 980 coercedHash = 0xfffffffe; 981 } 982 983 return getInet4Address(Ints.toByteArray(coercedHash)); 984 } 985 986 /** 987 * Returns an {@code int} hash of a 64-bit long. 988 * 989 * This comes from http://www.concentric.net/~ttwang/tech/inthash.htm 990 * 991 * This hash gives no guarantees on the cryptographic suitability nor the 992 * quality of randomness produced, and the mapping may change in the future. 993 * 994 * @param key A 64-bit number to hash 995 * @return {@code int} the input hashed into 32 bits 996 */ hash64To32(long key)997 @VisibleForTesting static int hash64To32(long key) { 998 key = (~key) + (key << 18); 999 key = key ^ (key >>> 31); 1000 key = key * 21; 1001 key = key ^ (key >>> 11); 1002 key = key + (key << 6); 1003 key = key ^ (key >>> 22); 1004 return (int) key; 1005 } 1006 1007 /** 1008 * Returns an integer representing an IPv4 address regardless of 1009 * whether the supplied argument is an IPv4 address or not. 1010 * 1011 * <p>IPv6 addresses are <b>coerced</b> to IPv4 addresses before being 1012 * converted to integers. 1013 * 1014 * <p>As long as there are applications that assume that all IP addresses 1015 * are IPv4 addresses and can therefore be converted safely to integers 1016 * (for whatever purpose) this function can be used to handle IPv6 1017 * addresses as well until the application is suitably fixed. 1018 * 1019 * <p>NOTE: an IPv6 address coerced to an IPv4 address can only be used 1020 * for such purposes as rudimentary identification or indexing into a 1021 * collection of real {@link InetAddress}es. They cannot be used as 1022 * real addresses for the purposes of network communication. 1023 * 1024 * @param ip {@link InetAddress} to convert 1025 * @return {@code int}, "coerced" if ip is not an IPv4 address 1026 * @since 7.0 1027 */ coerceToInteger(InetAddress ip)1028 public static int coerceToInteger(InetAddress ip) { 1029 return ByteStreams.newDataInput(getCoercedIPv4Address(ip).getAddress()).readInt(); 1030 } 1031 1032 /** 1033 * Returns an Inet4Address having the integer value specified by 1034 * the argument. 1035 * 1036 * @param address {@code int}, the 32bit integer address to be converted 1037 * @return {@link Inet4Address} equivalent of the argument 1038 */ fromInteger(int address)1039 public static Inet4Address fromInteger(int address) { 1040 return getInet4Address(Ints.toByteArray(address)); 1041 } 1042 1043 /** 1044 * Returns an address from a <b>little-endian ordered</b> byte array 1045 * (the opposite of what {@link InetAddress#getByAddress} expects). 1046 * 1047 * <p>IPv4 address byte array must be 4 bytes long and IPv6 byte array 1048 * must be 16 bytes long. 1049 * 1050 * @param addr the raw IP address in little-endian byte order 1051 * @return an InetAddress object created from the raw IP address 1052 * @throws UnknownHostException if IP address is of illegal length 1053 */ fromLittleEndianByteArray(byte[] addr)1054 public static InetAddress fromLittleEndianByteArray(byte[] addr) 1055 throws UnknownHostException { 1056 byte[] reversed = new byte[addr.length]; 1057 for (int i = 0; i < addr.length; i++) { 1058 reversed[i] = addr[addr.length - i - 1]; 1059 } 1060 return InetAddress.getByAddress(reversed); 1061 } 1062 1063 /** 1064 * Returns a new InetAddress that is one more than the passed in address. 1065 * This method works for both IPv4 and IPv6 addresses. 1066 * 1067 * @param address the InetAddress to increment 1068 * @return a new InetAddress that is one more than the passed in address. 1069 * @throws IllegalArgumentException if InetAddress is at the end of its 1070 * range. 1071 * @since 10.0 1072 */ increment(InetAddress address)1073 public static InetAddress increment(InetAddress address) { 1074 byte[] addr = address.getAddress(); 1075 int i = addr.length - 1; 1076 while (i >= 0 && addr[i] == (byte) 0xff) { 1077 addr[i] = 0; 1078 i--; 1079 } 1080 1081 Preconditions.checkArgument(i >= 0, "Incrementing %s would wrap.", address); 1082 1083 addr[i]++; 1084 try { 1085 return InetAddress.getByAddress(addr); 1086 } catch (UnknownHostException e) { 1087 throw new AssertionError(e); 1088 } 1089 } 1090 1091 /** 1092 * Returns true if the InetAddress is either 255.255.255.255 for IPv4 or 1093 * ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6. 1094 * 1095 * @return true if the InetAddress is either 255.255.255.255 for IPv4 or 1096 * ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6. 1097 * @since 10.0 1098 */ isMaximum(InetAddress address)1099 public static boolean isMaximum(InetAddress address) { 1100 byte[] addr = address.getAddress(); 1101 for (int i = 0; i < addr.length; i++) { 1102 if (addr[i] != (byte) 0xff) { 1103 return false; 1104 } 1105 } 1106 return true; 1107 } 1108 1109 /** 1110 * This method emulates the Java 6 method 1111 * {@code Arrays.copyOfRange(byte, int, int)}, which is not available in 1112 * Java 5, and thus cannot be used in Guava code. 1113 */ copyOfRange(byte[] original, int from, int to)1114 private static byte[] copyOfRange(byte[] original, int from, int to) { 1115 Preconditions.checkNotNull(original); 1116 1117 int end = Math.min(to, original.length); 1118 byte[] result = new byte[to - from]; 1119 1120 System.arraycopy(original, from, result, 0, end - from); 1121 return result; 1122 } 1123 } 1124