IPIP-0512: Limit Identity CID Size to 128 Bytes in UnixFS Contexts

2. Motivation

Identity CIDs are unique in that they inline data directly into the CID itself rather than hashing it. Without clear limits, this creates several problems:

Resource Exhaustion: Poorly written clients could encode large payloads as identity CIDs and propagate them through the network, consuming bandwidth and resources without providing value.
Security Vulnerabilities: Identity CIDs provide no integrity verification and are vulnerable to bit flips. Large identity CIDs amplify this risk.
Unclear Boundaries: The ecosystem lacks clear guidelines on when identity CIDs are appropriate, leading to potential misuse.
CIDs as Data Containers: Without limits, identity CIDs could embed arbitrary amounts of data, effectively turning CIDs from content addresses into data containers.

As discussed in ipfs/boxo#1018, the community consensus is that large identity CIDs are problematic and a reasonable limit is needed.

3. Detailed design

This IPIP adds a new section to the UnixFS specification documenting the 128-byte digest size limit for identity CIDs:

3.1 Changes to UnixFS Specification

Add new section "Identity CID Size Limit" that specifies:

Identity CIDs (multihash code 0x00) are experimental and limited to 128-byte digest size
Implementations MUST never produce identity CIDs with digest sizes exceeding 128 bytes
Implementations MUST reject identity CIDs with digest sizes exceeding 128 bytes when reading
Implementations SHOULD automatically convert to regular blocks if data modifications would exceed the limit

3.2 Test Fixtures

Add invalid test case for a 129-byte identity CID that implementations MUST reject.

4. Design rationale

The 128-byte limit was chosen based on several factors:

Alignment with Existing Constraints: The limit matches DefaultMaxDigestSize already used for cryptographic hashes in the ecosystem. 128 bytes is a sensible limit that accommodates the digest sizes of the longest popular hash functions (e.g., SHA-512 produces 64-byte digests), while preventing unbounded growth.
Community Consensus: Key maintainers expressed support for this limit:
- @rvagg: "128 seems reasonable to me. I'm happy to have them squished down their happy-path use to a size where they're more likely being used for their size-saving utility"
- @vmx: "I'm not a fan of large identity CIDs... 128 bytes sound reasonable to me"
- @achingbrain: "It looks fine at first glance 👍" (confirming Helia compatibility)
Practical Usage: 128 bytes is sufficient for legitimate use cases (small inline data) while preventing abuse.
Implementation Precedent: This limit has been implemented in:
- GO: Boxo v0.35.0 (shipped in Kubo v0.38.1)
- JS: Helia UnixFS v6.0.1 (shipped in Helia v6.0.1)

4.1 User benefit

Protection from Resource Exhaustion: Users are protected from malicious or poorly-written clients that might otherwise propagate large identity CIDs.
Clear Guidelines: Developers have explicit boundaries for appropriate identity CID usage.
Consistent Behavior: All conforming implementations will handle identity CIDs consistently.
No Wasted Resources: Avoids unnecessary roundtrips where clients send data to remote services only to have the deserialized bytes sent back, when the client already had the data and could have avoided the entire network operation.

4.2 Compatibility

Identity CIDs have always been marked as experimental, and this change does not impact users who used default settings in software like Kubo or Helia, which never produced identity CIDs by default.

This is a breaking change only for any existing identity CIDs with digest sizes exceeding 128 bytes. However:

Existing valid identity CIDs (≤128 bytes) remain unaffected
The change has been tested in Kubo 0.38 RC1 to gather feedback
Most users are unaffected as identity CIDs require explicit opt-in

Implementations upgrading to support this IPIP will need to:

Add validation to reject oversized identity CIDs when reading
Prevent creation of identity CIDs exceeding the limit
Consider automatic conversion to regular blocks when data grows

4.3 Security

This change improves security by:

Preventing Unbounded Resource Consumption: Limits the amount of data that can be inlined in CIDs
Reducing Attack Surface: Smaller identity CIDs reduce the impact of bit flip vulnerabilities
Clear Security Boundaries: Explicit limits help security audits and threat modeling
Mitigating Known Vulnerabilities: The go-car library previously had a vulnerability (GHSA-9x4h-8wgm-8xfg) where decoding user-controlled identity CIDs could cause excessive memory allocation, leading to denial of service. While go-car mitigated this by capping allocations at 1MiB, establishing a 128-byte limit at the UnixFS specification level ensures all implementations are protected from this class of vulnerabilities by default.

4.4 Alternatives

Several alternatives were considered:

No Limit: Rejected due to resource exhaustion and abuse potential
Smaller Limit (32-64 bytes): Would break more existing use cases
Larger Limit (256+ bytes): As noted by @rvagg, "the higher you go, the harder it is to justify their use"
Complete Deprecation: Too disruptive; identity CIDs have legitimate uses for tiny data

5. Test fixtures

5.1 Valid Identity CID (128 bytes)

CID: bafkqbaabijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbeeqscijbee
Content: 128 'B' characters
Expected: Implementations MUST accept this CID

5.2 Invalid Identity CID (129 bytes)

CID: bafkqbaibifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqkbifaucqi
Content: 129 'A' characters
Expected: Implementations MUST reject this CID with an appropriate error