forString() incorrectly parsing IPv4 mapped IPv6 address

[wdec]

Guava Version

33.1.2

Description

When parsing an IPv4 mapped IPv6 address the InetAddresses.forString() incorrectly returns the address as a v4 address.

Example

String ::ffff:10.111.184.37 -> Inet4Address "/10.111.184.37"

Expected Behavior

The address should be returned as a v6 address.

Actual Behavior

Returned as an IPv4 object

Packages

com.google.common.net

Platforms

No response

Checklist

• I agree to follow the code of conduct.

• I can reproduce the bug with the latest version of Guava available.

[cpovirk]

I'm not sure who the best networking expert for me to ask about this is nowadays. Can you give me your analysis of the tradeoffs here? As a starting point, I asked Gemini, and I got the response below:

---

Here is a breakdown of the architectural and practical arguments for both approaches.

---

What is an IPv4-mapped IPv6 address?

Before weighing the arguments, it is helpful to visualize the structure. These addresses are defined in RFC 4291. They consist of 80 bits of zeros, 16 bits of ones, and then the 32 bits of the IPv4 address.

They are primarily used to allow IPv6 sockets to communicate with legacy IPv4 nodes.

---

Arguments for Returning an IPv6 Object

The "Purist" or "Structural" Approach.

Most standard libraries (like Python's ipaddress or Go's net package) often lean this way because, technically, the input is 128 bits long.

• Data Fidelity (Losslessness): If the input string was ::ffff:192.0.2.1, returning an IPv4 object (192.0.2.1) discards information. You have technically altered the data type from what was provided. Returning an IPv6 object preserves the exact state of the input.

• Socket API Consistency: In dual-stack socket programming, the operating system kernel often exposes these addresses as AF_INET6 (IPv6 family). If a library automatically converts them to IPv4, it creates a mismatch between the socket family and the address object, which can cause bugs in low-level networking code.

• Avoids Ambiguity: If the library converts mapped addresses to IPv4, but not compatible addresses (::192.0.2.1, which is deprecated but exists), the behavior becomes unpredictable. Treating all 128-bit inputs as IPv6 is a simpler, more deterministic rule.

• Security (Canonicalization): Automatic unmapping can be dangerous. If an Access Control List (ACL) blocks ::ffff:10.0.0.1 but allows 10.0.0.1, and your parser silently converts the former to the latter, you might accidentally bypass a security rule intended to block IPv6 traffic.

Arguments for Returning an IPv4 Object

The "Pragmatic" or "Semantic" Approach.

This approach argues that the identity of the host is what matters, not the container (the 128-bit format).

• Usability & Developer Intent: When a developer parses ::ffff:192.168.1.1, they usually want to know "Which machine is this?" The answer is the IPv4 host 192.168.1.1. Requiring the developer to manually "unmap" the address every time is cumbersome.

• Protocol Reality: An IPv4-mapped address is not valid for global IPv6 routing. It will never appear in an IPv6 packet header on the wire; it effectively is an IPv4 connection wrapped in an API abstraction. Treating it as IPv4 reflects the actual wire protocol being used.

• Database Compatibility: If you are storing IP addresses in a database column typed for IPv4 (e.g., PostgreSQL inet or a VARCHAR(15)), returning an IPv6 object forces the user to add type-checking logic before saving, whereas an IPv4 object would "just work."

---

Comparison Summary

Feature | Return as IPv6 | Return as IPv4 -- | -- | -- Strictness | High (Structure focused) | Low (Utility focused) Information Loss | None | Loses the ::ffff: prefix Socket Matching | Matches AF_INET6 | Matches AF_INET Best For | Systems programming, Firewalls | Web apps, Analytics, Logging

The "Hybrid" Solution

Many modern libraries solve this by returning an IPv6 object but providing a helper method. For example:

1. Return IPv6 by default: To maintain structural correctness.

2. Provide properties: Such as .ipv4_mapped (boolean) or .teredo (boolean).

3. Provide a method: Such as .map_to_ipv4() or .unwrap() which explicitly converts it to the IPv4 object if valid.

This forces the developer to be explicit about the conversion, mitigating security risks while acknowledging the utility of the underlying IPv4 address.

[cpovirk]

I dug up a comment in some long-deleted code that suggests that InetAddress.getByAddress might autoconvert. If that's the case, then that would be one argument in favor of making our method do the same.

[cpovirk]

This does seem to be the behavior of the JDK InetAddress.getByAddress, as well as that of InetAddress.ofLiteral, whose behavior is probably nice to match when we can:

$ cat Ipv6Map.java 
import java.net.InetAddress;
 
public class Ipv6Map {
  public static void main(String[] args) throws Exception {
    byte[] ipv6Bytes = {
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, (byte) 0xFF, (byte) 0xFF, 10, 111, (byte) 184, 37
    };
 
    var byAddress = InetAddress.getByAddress(ipv6Bytes);
    System.out.println(byAddress.getClass() + " " + byAddress);
 
    var ofLiteral = InetAddress.ofLiteral("::ffff:10.111.184.37");
    System.out.println(ofLiteral.getClass() + " " + ofLiteral);
  }
}

$ java Ipv6Map.java
class java.net.Inet4Address /10.111.184.37
class java.net.Inet4Address /10.111.184.37

[wdec]

The particular case where this was observed was when processing data acquired from network devices where some vendors expose an IPv6 address using this notation. It's problematic because it is a valid IPv6 address, as reported by the device, but the current net library's behavior makes it effectively a v4 address and checks for isIpv6 fail.

Canonically, an address like ::ffff:a.b.c.d is an IPv6 address type, not IPv4. What it gets used for is a different matter.

[cpovirk]

Thanks. As noted above, I don't know enough about networking to have an informed opinion, but you've got me vaguely uncomfortable with the current behavior. I'm not sure what it would take for me to be comfortable with actually changing the behavior, but it's a start.

Among the various obstacles to making a change is that the current behavior does seem to be baked deeply into Java. The only way I've found so far to force the creation of an Inet6Address is to pass a scope ID (or presumably NetworkInterface), but that results in a different value in ways that might matter:

$ cat Ipv6Map.java
import java.net.Inet6Address;
import java.net.InetAddress;
 
public class Ipv6Map {
  public static void main(String[] args) throws Exception {
    byte[] bytes = {
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, (byte) 0xFF, (byte) 0xFF, 10, 111, (byte) 184, 37
    };
    String string = "::ffff:10.111.184.37";
 
    print(InetAddress.ofLiteral(string));
    print(InetAddress.getByAddress(bytes));
    print(Inet6Address.ofLiteral(string));
    print(Inet6Address.getByAddress(string, bytes, /* scope_id= */ 0));
  }
 
  static void print(InetAddress address) {
    System.out.println(address.getClass() + " " + address);
  }
}

$ java Ipv6Map.java
class java.net.Inet4Address /10.111.184.37
class java.net.Inet4Address /10.111.184.37
class java.net.Inet4Address /10.111.184.37
class java.net.Inet6Address ::ffff:10.111.184.37/0:0:0:0:0:ffff:a6f:b825%0

I suspect that we'll end up stuck the way we are now, though it's always possible that we'll learn new things that will change that.