Websocket Transport

[acul71]

WebSocket Protocol Implementation Compliance Analysis

Date: August 2025
Project: py-libp2p WebSocket Transport Implementation
Specification Reference: libp2p WebSocket Spec

Executive Summary

Our current WebSocket implementation in py-libp2p is PARTIALLY COMPLIANT with the official libp2p WebSocket specification. We have implemented a robust foundation with /ws protocol support, DNS addressing, IPv6 support, and proper libp2p integration. However, we are missing critical security features (/wss, /tls/ws, /tls/sni/domain/ws) and port defaulting behavior required for full specification compliance.

Compliance Level: 🟡 PARTIALLY COMPLIANT

Current Implementation Status

✅ What We Have Implemented

1. Basic WebSocket Transport: WebsocketTransport class
2. Transport Registry Integration: Registration and handling of ws protocol
3. Multiaddr Validation: Comprehensive validation for /ip4/addr/tcp/port/ws, /ip6/addr/tcp/port/ws, and DNS formats
4. Transport Creation: Ability to create WebSocket transports for valid multiaddrs
5. DNS Addressing: Full support for /dns/domain/tcp/port/ws, /dns4/domain/tcp/port/ws, /dns6/domain/tcp/port/ws
6. IPv6 Support: Full support for IPv6 addresses
7. Security Integration: Works with Noise encryption protocol
8. Production Ready: Robust implementation suitable for non-TLS production scenarios
9. SSL Infrastructure: Python's built-in ssl module and trio-websocket SSL support available

❌ What We Are Missing (Critical Gaps)

1. Security Protocols: No support for /wss, /tls/ws, or /tls/sni/domain/ws (explicitly throws NotImplementedError)
2. Port Defaulting: No automatic port assignment (80 for /ws, 443 for secure variants)
3. TLS Integration: No certificate handling or TLS context configuration
4. SNI Support: No Server Name Indication support for TLS certificate validation
5. Multiaddr Format Support: Limited to /ws only, missing secure variants

TLS vs WSS: Critical Distinction

Two Different Security Mechanisms

Based on our research of Go and JavaScript implementations, there are two distinct security layers in libp2p:

1. Transport Layer Security (WSS) - Standard TLS

• Purpose: Secure WebSocket transport layer
• Implementation: Uses standard TLS/SSL packages
• Protocol: Standard TLS 1.3 over WebSocket
• OSI Layer: Layer 4 (Transport)
• Examples:

  /ip4/192.0.2.0/tcp/8080/wss
  /ip4/192.0.2.0/tcp/8080/tls/ws
  /dns/example.com/tcp/443/wss
  

Evidence from implementations:

• Go: Uses crypto/tls package for WSS (standard TLS)
• JavaScript: Uses Node.js https module for WSS (standard TLS)
• Python: Can use ssl module + trio-websocket SSL support

2. Application Layer Security (libp2p TLS) - Custom Protocol

• Purpose: Connection encryption and peer authentication
• Implementation: Custom libp2p TLS protocol (/tls/1.0.0)
• Protocol: Built on TLS 1.3 but with custom X.509 extensions
• OSI Layer: Layer 6 (Presentation)
• Examples:

  /ip4/192.0.2.0/tcp/8080/ws/p2p/QmPeerID  # WS + libp2p TLS (negotiated)
  /ip4/192.0.2.0/tcp/8080/wss/p2p/QmPeerID # WSS + libp2p TLS (negotiated)
  

Key Differences:

• WSS: Transport layer, uses standard TLS packages
• libp2p TLS: Application layer, uses custom protocol with peer authentication
• Integration: WSS provides transport security, libp2p TLS provides application security

OSI Layer Architecture in libp2p

Based on the libp2p specifications, here's the complete OSI layer mapping:

libp2p Protocol Stack by OSI Layer

OSI Layer	libp2p Components	Protocols	Purpose
Layer 7 (Application)	Application Protocols	/ping/1.0.0, /identify/1.0.0, /kad/1.0.0, /pubsub/1.0.0	Application-specific protocols
Layer 6 (Presentation)	Security Protocols	/tls/1.0.0, /noise/1.0.0, /secio/1.0.0	Connection encryption, peer authentication
Layer 5 (Session)	Stream Multiplexing	/yamux/1.0.0, /mplex/1.0.0	Stream multiplexing over connections
Layer 4 (Transport)	Transport Protocols	/tcp, /ws, /wss, /quic, /webrtc	Reliable data transfer
Layer 3 (Network)	Addressing	/ip4, /ip6, /dns, /dns4, /dns6	Network addressing and routing
Layer 2 (Data Link)	Link Layer	(OS/hardware dependent)	Local network communication
Layer 1 (Physical)	Physical Layer	(OS/hardware dependent)	Physical transmission

Connection Upgrade Process

Application Protocols (Layer 7)
    ├── /ping/1.0.0
    ├── /identify/1.0.0
    └── /pubsub/1.0.0
    ↓
Security Negotiation (Layer 6)
    ├── /tls/1.0.0 (libp2p TLS)
    ├── /noise/1.0.0 (Noise Protocol)
    └── /secio/1.0.0 (Legacy)
    ↓
Stream Multiplexing (Layer 5)
    ├── /yamux/1.0.0
    └── /mplex/1.0.0
    ↓
Raw Transport Connection (Layer 4)

Transport Registry Role

The transport registry operates at Layer 4 and handles:

• Transport protocol registration (/ws, /wss, /tcp, /quic)
• Multiaddr validation for transport protocols
• Transport creation and management

It does NOT handle:

• Security protocols (Layer 6) - handled by connection upgrader
• Stream multiplexing (Layer 5) - handled by connection upgrader
• Application protocols (Layer 7) - handled by protocol handlers

Multiaddr Format Analysis

Supported vs Required Formats

Protocol	Specification	Our Implementation	Status	Description
/ws	✅ Required	✅ FULLY IMPLEMENTED	COMPLIANT	Insecure WebSocket
/wss	✅ Required	❌ NotImplementedError	NON-COMPLIANT	Secure WebSocket (shorthand for /tls/ws)
/tls/ws	✅ Required	❌ Not Implemented	NON-COMPLIANT	Secure WebSocket (explicit TLS)
/tls/sni/domain/ws	✅ Required	❌ Not Implemented	NON-COMPLIANT	Secure WebSocket with explicit SNI
/dns/domain/ws	✅ Required	✅ FULLY IMPLEMENTED	COMPLIANT	DNS-based insecure WebSocket
/dns/domain/wss	✅ Required	❌ Not Implemented	NON-COMPLIANT	DNS-based secure WebSocket
/ip6/addr/ws	✅ Required	✅ FULLY IMPLEMENTED	COMPLIANT	IPv6 insecure WebSocket

Multiaddr Format Differences Explained

1. /wss vs /tls/ws

• /wss is a shorthand for /tls/ws
• Both indicate secure WebSocket connections over TLS
• Both default to TCP port 443 when no port is specified
• Examples:

  /ip4/192.0.2.0/tcp/1234/wss
  /ip4/192.0.2.0/tcp/1234/tls/ws
  

2. /tls/sni/domain/ws vs /dns/domain/ws

• /tls/sni/domain/ws: Uses resolved IP address with explicit SNI
  • Format: /ip4/resolved_ip/tcp/port/tls/sni/domain.com/ws
  • SNI value used for TLS certificate validation
• /dns/domain/ws: Uses DNS name with implicit SNI
  • Format: /dns/domain.com/tcp/port/ws
  • DNS name automatically becomes SNI value

3. Port Defaulting Behavior

Format	Default Port	Example
/ip4/addr/ws	80	/ip4/192.0.2.0/ws → port 80
/ip4/addr/wss	443	/ip4/192.0.2.0/wss → port 443
/ip4/addr/tls/ws	443	/ip4/192.0.2.0/tls/ws → port 443
/dns/domain/ws	80	/dns/example.com/ws → port 80
/dns/domain/wss	443	/dns/example.com/wss → port 443

Technical Implementation Analysis

Current Infrastructure Readiness

✅ Available Components:

• Python's built-in ssl module (comprehensive TLS support)
• trio-websocket>=0.11.0 (already supports SSL/TLS)
• Transport registry framework
• Multiaddr validation infrastructure

✅ trio-websocket SSL Support:

# Client-side SSL support
open_websocket_url(url, ssl_context=ssl_context)

# Server-side SSL support  
serve_websocket(handler, host, port, ssl_context=ssl_context)

Required Changes for Full Compliance

Phase 1: Multiaddr Format Support (Critical)

# Remove NotImplementedError and add support for:
- /wss (shorthand for /tls/ws)
- /tls/ws (explicit TLS)
- /tls/sni/domain/ws (SNI support)
- /dns/domain/wss (DNS-based secure)

Phase 2: Port Defaulting

# Implement automatic port assignment:
- /ws → TCP port 80
- /wss, /tls/ws → TCP port 443

Phase 3: TLS Infrastructure

# Add TLS certificate handling:
- Certificate loading and validation
- SNI support
- Secure context management

Implementation Recommendations

1. Use Standard TLS Infrastructure for WSS

Standard TLS packages are sufficient for WSS - Python's ssl module + trio-websocket's SSL support is all that's needed for WebSocket Secure transport layer security.

Evidence from other implementations:

• Go: Uses crypto/tls package for WSS
• JavaScript: Uses Node.js https module for WSS
• Both use standard TLS, not custom libp2p TLS for WSS

2. Clarify Security Layer Distinction

Two different security mechanisms:

1. Transport Layer Security (WSS): Uses standard TLS/HTTPS

   # WSS uses standard SSL context
   ssl_context = ssl.create_default_context()
   ws_context = open_websocket_url("wss://example.com:443/", ssl_context=ssl_context)

2. Application Layer Security (libp2p TLS): Custom protocol (/tls/1.0.0) for connection encryption

   # This is handled by the connection upgrader, not the transport
   # Protocol negotiation: /tls/1.0.0, /noise/1.0.0, etc.

3. Extend Current WebSocket Transport

class WebsocketTransport(ITransport):
    def __init__(self, upgrader: TransportUpgrader, ssl_context: ssl.SSLContext = None):
        self._upgrader = upgrader
        self._ssl_context = ssl_context  # Standard SSL context for WSS
    
    async def dial(self, maddr: Multiaddr) -> RawConnection:
        # Check if WSS
        is_wss = str(maddr).endswith("/wss") or "tls" in [p.name for p in maddr.protocols()]
        ws_url = f"wss://{host}:{port}/" if is_wss else f"ws://{host}:{port}/"
        
        # Use standard SSL context for WSS
        ssl_context = self._ssl_context if is_wss else None
        ws_context = open_websocket_url(ws_url, ssl_context=ssl_context)

4. Update Transport Registry

def _is_valid_websocket_multiaddr(maddr: Multiaddr) -> bool:
    protocols = [proto.name for proto in maddr.protocols()]
    
    # Support both /ws and /wss
    if protocols[-1].name not in ["ws", "wss"]:
        return False
    
    # Support /tls/ws patterns
    if "tls" in protocols:
        # Validate TLS structure
        pass
    
    return True

Conclusion

Our current WebSocket implementation provides a robust foundation with comprehensive support for /ws protocol, DNS addressing, IPv6, and proper libp2p integration. The implementation is production-ready for non-TLS scenarios and demonstrates solid engineering practices.

Key Strengths:

• ✅ Full /ws protocol implementation
• ✅ DNS addressing support (IPv4, IPv6, DNS4, DNS6)
• ✅ Proper libp2p integration
• ✅ Noise encryption support
• ✅ Working examples and tests
• ✅ Comprehensive multiaddr validation
• ✅ SSL infrastructure available (Python ssl + trio-websocket)

Primary Gaps:

• ❌ TLS support (/wss, /tls/ws, /tls/sni/domain/ws) - This is the main missing piece
• ❌ Port defaulting behavior (80/443 defaults)
• ❌ SNI support for certificate validation

Implementation Path:
The path to full compliance is straightforward since all required infrastructure is already available. The main work involves:

1. Extending multiaddr parsing to support secure variants
2. Adding port defaulting logic
3. Integrating SSL contexts with the existing WebSocket transport
4. Updating the transport registry

Standard TLS packages are sufficient for WSS - the existing Python SSL infrastructure is all that's needed for WebSocket Secure transport layer security. The custom libp2p TLS protocol (/tls/1.0.0) is used for additional application-layer security after the WebSocket connection is established.

[acul71]

WebSocket Multiaddr Examples

Source: libp2p specifications
Date: August 2025

Transport Addresses (No Peer ID)

Insecure WebSocket

/ip4/192.0.2.0/tcp/8080/ws                    # WS transport with explicit port
/ip4/192.0.2.0/ws                             # WS transport (defaults to port 80)
/dns/example.com/tcp/8080/ws                   # DNS-based WS transport
/dns/example.com/ws                            # DNS-based WS (defaults to port 80)
/ip6/2001:db8::1/tcp/8080/ws                  # IPv6 WS transport

Secure WebSocket (WSS)

/ip4/192.0.2.0/tcp/8080/wss                   # WSS transport (shorthand for /tls/ws)
/ip4/192.0.2.0/tcp/8080/tls/ws                # WSS transport (explicit TLS)
/ip4/192.0.2.0/wss                            # WSS transport (defaults to port 443)
/ip4/192.0.2.0/tls/ws                         # WSS transport (defaults to port 443)
/dns/example.com/tcp/443/wss                   # DNS-based WSS transport
/dns/example.com/wss                           # DNS-based WSS (defaults to port 443)
/ip6/2001:db8::1/tcp/443/wss                  # IPv6 WSS transport

WSS with SNI (Server Name Indication)

/ip4/192.0.2.0/tcp/8080/tls/sni/example.com/ws  # WSS with explicit SNI

WSS with HTTP Path

/dns/example.com/wss/http-path/path%2Fto%2Fendpoint  # WSS with HTTP path

Peer Addresses (With Peer ID)

WS + Peer ID

/ip4/192.0.2.0/tcp/8080/ws/p2p/QmPeerID       # WS transport + peer ID
/dns/example.com/tcp/8080/ws/p2p/QmPeerID      # DNS-based WS + peer ID

WSS + Peer ID

/ip4/192.0.2.0/tcp/8080/wss/p2p/QmPeerID      # WSS transport + peer ID
/dns/example.com/tcp/443/wss/p2p/QmPeerID      # DNS-based WSS + peer ID

Real-World Examples from libp2p Bootstrap Nodes

/dns6/am6.bootstrap.libp2p.io/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb
/dns4/am6.bootstrap.libp2p.io/tcp/443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb

Port Defaulting Behavior

Format	Default Port	Example
/ip4/addr/ws	80	/ip4/192.0.2.0/ws → port 80
/ip4/addr/wss	443	/ip4/192.0.2.0/wss → port 443
/ip4/addr/tls/ws	443	/ip4/192.0.2.0/tls/ws → port 443
/dns/domain/ws	80	/dns/example.com/ws → port 80
/dns/domain/wss	443	/dns/example.com/wss → port 443

Notes

• WSS is shorthand for /tls/ws
• Security protocols (/tls/1.0.0, /noise/1.0.0) are negotiated during connection establishment, not specified in multiaddr
• Peer addresses always include /p2p/PeerID for libp2p peer identification
• SNI allows explicit specification of the server name for TLS certificate validation
• HTTP paths can be added to WebSocket addresses for routing