ipcidr Protocol Usage in libp2p

[acul71]

ipcidr Protocol Usage in libp2p

Overview

The ipcidr protocol is a multiaddr protocol extension that allows specifying CIDR (Classless Inter-Domain Routing) notation for IP address ranges. This protocol is used across different libp2p implementations for network access control, connection management, and resource allocation.

Protocol Status by Implementation

Implementation	Support Status	Notes
Go libp2p	✅ Official Support	Built into multiaddr library
JavaScript libp2p	⚠️ Custom Extension	Not in official multiaddr spec
Python libp2p	❌ Not Supported	No implementation found

Go libp2p Implementation

Basic Usage

// IPv4 CIDR notation
multiaddr.StringCast("/ip4/1.2.3.0/ipcidr/24")    // 1.2.3.0/24 network
multiaddr.StringCast("/ip4/192.168.1.0/ipcidr/24") // 192.168.1.0/24 network
multiaddr.StringCast("/ip4/0.0.0.0/ipcidr/0")      // All IPv4 addresses

// IPv6 CIDR notation
multiaddr.StringCast("/ip6/1:2:3::/ipcidr/58")     // IPv6 network
multiaddr.StringCast("/ip6/2001:db8::/ipcidr/64")  // IPv6 network

Resource Manager Allowlist

// Create resource manager with allowlisted multiaddrs
rcmgr, err := NewResourceManager(
    NewFixedLimiter(limits), 
    WithAllowlistedMultiaddrs([]multiaddr.Multiaddr{
        // Single IP address
        multiaddr.StringCast("/ip4/1.2.3.4"),
        // Specific peer on specific IP
        multiaddr.StringCast("/ip4/2.2.3.4/p2p/" + peerID.String()),
        // Network range
        multiaddr.StringCast("/ip4/1.2.3.0/ipcidr/24"),
        // IPv6 network
        multiaddr.StringCast("/ip6/1:2:3::/ipcidr/58"),
    })
)

Network Prefix Limits

// Set connection limits per network prefix
rcmgr, err := NewResourceManager(
    NewFixedLimiter(limits), 
    WithAllowlistedMultiaddrs([]multiaddr.Multiaddr{
        multiaddr.StringCast("/ip4/1.2.3.0/ipcidr/24"),
    }),
    WithNetworkPrefixLimit([]NetworkPrefixLimit{
        {Network: netip.MustParsePrefix("1.2.3.0/24"), ConnCount: 8},
    }, []NetworkPrefixLimit{})
)

Protocol Detection

// Check if component is ipcidr protocol
if c.Protocol().Code == multiaddr.P_IPCIDR {
    mask = c.Value()
}

// Parse CIDR notation
_, ipnet, err := net.ParseCIDR(ipString + "/" + mask)

JavaScript libp2p Implementation

Basic Usage

// IPv4 CIDR notation
multiaddr('/ip4/127.0.0.1/ipcidr/32')     // Single IP
multiaddr('/ip4/192.168.1.1/ipcidr/24')   // Network subnet
multiaddr('/ip4/83.13.55.32/ipcidr/32')  // Single IP with explicit CIDR

// IPv6 CIDR notation
multiaddr('/ip6/::1/ipcidr/128')           // IPv6 loopback
multiaddr('/ip6/2001:db8::/ipcidr/64')    // IPv6 network
multiaddr('/ip6/2001:db8::1/ipcidr/128')  // Single IPv6 address

Connection Manager Usage

// Connection manager with allow/deny lists
const connectionManager = new DefaultConnectionManager({
  allow: [
    '/ip4/83.13.55.32/ipcidr/32', // Allow single IP
    '/ip4/192.168.1.1/ipcidr/24'  // Allow network subnet
  ],
  deny: [
    '/ip4/83.13.55.0/ipcidr/24',  // Deny IPv4 subnet
    '/ip6/2001:db8::/ipcidr/64'   // Deny IPv6 subnet
  ]
})

Network Configuration

// IPv4 network config with CIDR
const ip4Config = {
  type: 'ip4',
  host: '192.168.1.1',
  cidr: 24  // /24 subnet
}

// IPv6 network config with CIDR  
const ip6Config = {
  type: 'ip6', 
  host: '2001:db8::1',
  cidr: '64'  // /64 subnet
}

Multiaddr to IpNet Conversion

// Convert multiaddr with ipcidr to IpNet
const ma = multiaddr('/ip4/192.168.1.1/ipcidr/24')
const ipNet = multiaddrToIpNet(ma)
// Result: '192.168.1.0/24'

const ma6 = multiaddr('/ip6/2001:db8::/ipcidr/64') 
const ipNet6 = multiaddrToIpNet(ma6)
// Result: '2001:0db8:0000:0000:0000:0000:0000:0000/64'

Python libp2p Implementation

Current Status

❌ Not Supported: The Python libp2p implementation does not currently support the ipcidr protocol.

Use Cases

1. Eclipse Attack Prevention

Allow trusted peers to connect even when under attack by specifying trusted IP ranges.

2. Network Access Control

Restrict connections to specific IP ranges for security purposes.

3. Resource Management

Set connection limits per network prefix to prevent resource exhaustion.

4. Peer Authentication

Combine IP ranges with specific peer IDs for enhanced security.

Default CIDR Behavior

When no ipcidr is specified, implementations typically add:

• /32 CIDR for IPv4 addresses (single host)
• /128 CIDR for IPv6 addresses (single host)

// These are equivalent in Go:
multiaddr.StringCast("/ip4/1.2.3.4")
multiaddr.StringCast("/ip4/1.2.3.4/ipcidr/32")

// These are equivalent in JavaScript:
multiaddr('/ip4/127.0.0.1')
multiaddr('/ip4/127.0.0.1/ipcidr/32')

Implementation Differences

Go libp2p

• ✅ Official support in multiaddr library
• ✅ Resource Manager integration
• ✅ Network prefix limits
• ✅ Peer-specific allowlists

JavaScript libp2p

• ⚠️ Custom extension (not in official spec)
• ✅ Connection Manager integration
• ✅ Network configuration support
• ✅ Multiaddr to IpNet conversion

Python libp2p

• ❌ Not implemented
• ❌ No CIDR support
• ❌ No network range filtering

Security Considerations

1. Eclipse Attack Prevention: The ipcidr protocol helps prevent eclipse attacks by ensuring trusted peers can always connect.

2. Resource Exhaustion: Network prefix limits prevent resource exhaustion from specific IP ranges.

3. Access Control: Fine-grained control over which IP ranges can connect to the node.

4. Peer Authentication: Combination of IP ranges and peer IDs provides enhanced security.

Future Considerations

For Python libp2p implementation, adding ipcidr support would require:

1. Connection Manager: Implement allowlist functionality
2. Resource Management: Add network prefix limits
3. Testing: Comprehensive test coverage for CIDR functionality

References

• Go libp2p Resource Manager
• JavaScript libp2p Connection Manager
• Multiaddr Protocol Table
• libp2p Addressing Specification

[seetadev]

@acul71 : Thank you for sharing this fantastic compilation on ipcidr. Appreciate it.

Wish to share that I have reviewed + merged ipcidr protocol addition in py-multiaddr: please visit multiformats/py-multiaddr#95

Wish to recommend you to get in touch with Paul and collaborate on a new release of py-multiaddr.

In the meantime, I will review the other missing protocols in py-multiaddr and will start working with you and Abhinav on it.