libp2p Connectivity

Standalone ⇄ Standalone
Browser to Standalone
Browser ⇄ Browser

Standalone ⇄ Standalone
Back
Browser to Standalone
Back
- WebSocket
- WebTransport
Browser ⇄ Browser
Back
- WebRTC

libp2p Connectivity

By supporting a wide range of transport protocols, libp2p enables universal connectivity between nodes across different network positions.

A primary goal of the libp2p project is universal connectivity. However, libp2p nodes may run on host machines or in browsers; they may be publically reachable or private. Thus, connectivity across these barriers has been historically out of reach.

Support for new protocols and our own advancements in libp2p helped us overcome these hurdles.

For developers using libp2p to build an application, we hope this site will help you learn more about how libp2p achieves universal connectivity across networks, how it will improve in the future, and how you can get involved!

Chat With Developers

Types of Connectivity

TCP

TCP was developed in the 1970s, and carried, up to the introduction of QUIC (see next section), the vast majority of traffic on the internet. It was also the first transport that was adopted in libp2p. To learn why it is not supported in browsers, see the Browser → Standalone Node section further below.

TCP in libp2p
Counting Round Trips

TCP in libp2p

Establishing a libp2p connection on top of TCP takes a few steps, upgrading the underlying connection:

Dial a TCP connection to the remote node and perform the 3-way-handshake
Negotiate a security protocol (Noise or TLS 1.3), and then perform the chosen cryptographic handshake. The connection is now encrypted and the peers have verified each others' peer IDs.
Apply a stream multiplexer (yamux or mplex).

Setting up a the libp2p takes quite a few network roundtrips, but is the most reliable option, as very few networks block TCP connections.

Counting Round Trips

TCP Handshake (1 RTT)
Multistream Negotiation of the Security Protocol (1 RTT)
Security Handshake: TLS 1.3 or Noise (1 RTT)
Multistream Negotiation of the Stream Multiplexer (1 RTT)

Establishing and "upgrading" (applying encryption and a stream multiplexer) takes a whopping 4 round trips.

And this is the most optimistic assumption. In case the peer doesn’t support the protocol suggested in a Multistream Negotiation step, Multistream will incur additional round trips.

Support

Possible

go-libp2p
rust-libp2p
node.js-libp2p

Not Possible

Chrome
Firefox
Safari

Get Involved

This is a very new protocol, and we can use your help.

QUIC

QUIC is a new UDP-based transport protocol. QUIC connections are always encrypted (using TLS 1.3) and provides native stream multiplexing.

Whenever possible, QUIC should be preferred over TCP. Not only is it faster, it also increases the chances of a successful holepunch in case of firewalls (see next section).

However: UDP is blocked in ~5-10% of networks, especially in corporate networks, so running a node exclusively with QUIC is usually not an option.

QUIC in libp2p
Counting Round Trips

QUIC in libp2p

Since QUIC provides encryption and stream multiplexing at the transport layer, no "upgrading" is required: As soon as the QUIC handshake finishes, we can use the QUIC connection as a libp2p connection.

To verify the remote’s peer ID, it is added to the TLS certificate (including a signature using the host’s key) which is used during the handshake. Once the handshake is complete, both sides have cryptographically verified each other’s identity.

Counting Round Trips

QUIC handshake (1-RTT)

That’s all there is. QUIC verifies the client’s address (that’s what TCP’s 3-way handshake is there for) and performs the TLS 1.3 handshake in parallel. And since QUIC comes with transport-level stream multiplexing, we don’t need to set up a separate stream multiplexer.

For resumed connections, QUIC even supports a 0-RTT handshake, although we’re currently not (yet) making use of that in libp2p.

Support

Possible

go-libp2
node.js-libp2p

Not Possible

Chrome
Firefox
Safari

Work In Progress

rust-libp2p

Hole Punching

TCP and QUIC by themselves are enough for establishing communication between public nodes; however, not all nodes are located in a publicly reachable position. Nodes in home or corporate networks are private and usually separated from the public internet by a NAT or a firewall. Mobile phones are also usually behind a so-called "carrier-grade NAT".

Nodes behind firewalls/NATs can dial any node on the public internet, but they cannot receive incoming connections from outside their local network.

Therefore, we introduced a novel decentralized hole punching mechanism in libp2p to enable connectivity between public and private nodes.

libp2p Relays
Obtaining a Direct Connection

libp2p Relays

When a libp2p node boots up, one of the first things it does is to start AutoNAT to determine its position in the network: is it a public node, reachable from the public internet, or is it a private node, located behind a firewall or a NAT?

A private node will start looking for relay servers on the network, and obtain a reservation with (at least) one of them. This entails keeping a connection open to that relay. The relay will now forward traffic from other nodes.
A public node will become a relay server, offering relay services to private nodes on the network. The relay service is designed such that it’s very cheap to run (in terms of CPU, memory and bandwith). This is achieved by limiting the number of reservations, the connection time for relayed connections as well as their bandwidth.

Obtaining a Direct Connection

Obtaining a reservation with a relay is only half the story. After all, relayed connections are limited both in terms of time and bandwidth. Nodes use relayed connections to coordinate the establishment of a direct connection.

We need to distinguish two situations here:

The node trying to connect is a public node: This is the easier scenario. When the node behind the NAT accepts the relayed connection, it notices that the peer has a public IP address. It then dials a direct connection to that node.
The other node is also behind a NAT: Simply dialing the peer won't work. It’s necessary to employ a technique called “hole punching”. By carefully timing simultaneous connection attempts from both sides the NATs on both sides are tricked into thinking that they’re both handling with outgoing connections.

Setting up the direct connection requires quite some effort, but it’s worth it: direct connections have a lower possible, and can use the full bandwidth of the link.

Support

Possible

go-libp2p

rust-libp2p

js-libp2p

Browser → Standalone Node

Enabling users and app developers to run fully functioning nodes in the browser has been a goal of the libp2p project for some time. Yet seamless connectivity had been out of reach until significant changes in browsers as of late. Here we outline existing ways of establishing connectivity and modern advances such as WebTransport.

Browsers mostly use HTTP(S), making use of an underlying TCP connection for HTTP/1.1 and HTTP/2, or a QUIC connection for HTTP/3. To keep their users secure, they enforce strict rules, like certificate requirements and blocking of cross-origin policies. For security reasons, it's not possible for a browser to dial a raw TCP or QUIC connection from within the browser, and all connections have to meet Secure Context requirements such as messages delivered over TLS.

Traditionally, WebSocket could be used to gain access to the underlying to the underlying TCP connection, after a so-called WebSocket Upgrade. Similarly, WebTransport aims to allow access to the underlying QUIC connection for HTTP/3.

Streams vs. Request-Response

HTTP is a request-response scheme. The client (browser) sends a request, and then waits for a response.

libp2p on the other hand is built on top of a stream abstraction. A stream is more flexible than a request-response scheme: it allows continuous bidirectional communication, both parties can send and receive data at any time.

WebSocket

WebSocket allows “hijacking” of a HTTP/1.1 connection. Later on, it was later also standardized for HTTP/2.

After an HTTP-based "Upgrade request", the browser gains access to the underlying TCP connection.

WebSocket Upgrade
WebSocket in libp2p
TLS Certificate Verification in the Browser
ACME to the rescue?

WebSocket Upgrade

The browser first establishes the TCP connection and sends an HTTP request.

The server can accept this upgrade request by sending a HTTP 200 response. All bytes sent on the TCP connection after this are now not considered part of the HTTP response anymore, but part of the WebSocket connection.

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade

WebSocket in libp2p

TCP handshake (1 RTT)
WebSocket Upgrade Request (1 RTT).
Multistream security protocol negotiation (1 RTT)
Security Handshake (Noise or TLS, 1 RTT)
Multistream stream multiplexer negotiation (1 RTT)

5 round trips is quite a long time for setting up a connection.

Unfortunately, this is not even the whole story. In recent years, the web has moved towards ubiquitous encryption, and browsers have started enforcing that web content is loaded via encrypted connection. Specifically, when on a website loaded via HTTPS, browsers will block plaintext WebSocket connections, and require a WebSocket Secure (wss) connection.

A WebSocket Secure connection uses HTTPS to perform the Upgrade request. That means that in addition to the 5 round trips listed above, there’ll be another roundtrip for the TLS handshake, increasing the handshake latency to 6 RTTs.

TLS Certificate Verification in the Browser

When establishing a connection to a web server, the client asks the server for a TLS certificate. Conceptually, the TLS certificate says “the domain libp2p.io belongs to the owner of this certificate”, together with a (cryptographic) signature.

Of course, the browser can’t just trust any signature. If an attacker wanted to impersonate libp2p.io, she could just sign her own certificate. Browsers are shipped with a list of signatories, called Certificate Authorities (CA) that they trust.

This is a problem for libp2p. Most nodes on the network don’t even have a domain name, let alone a certificate signed by a CA. Only a handful of nodes fulfil these properties, making WebSocket a niche transport in the libp2p ecosytem.

ACME to the rescue?

ACME is a protocol which allows a server to obtain a certificate from a CA without any manual involvement. There've been proposals to use ACME to issue a Let's Encrypt certificate for every libp2p node.

To be able to issue the certificate, the CA needs to verify that the server actually controls the domain. There are 2 ways:

HTTP / TLS challenge: The CA instructs the server to publish a random value on the website. It then issues a request to check the value. By being able to publish this value, the server has proven to control the domain.
DNS challenge: The CA instructs the server to publish the random value in a DNS TXT record. The server thereby proves that it can modify the DNS records for that domain.

There are a couple of problems with this approach:

libp2p nodes would still need to possess a domain name.
Using the HTTP / TLS challenge requires the node to start a webserver on port 80 or 443. This might not be possible if the node is running a webserver at the same time.
The DNS challenge requires (programmatic) access to the DNS records for the domain, which requires special configuration.

Support

Possible

go-libp2p
rust-libp2p
Chrome
Firefox
Safari

Work In Progress

node.js-libp2p2

Get Involved

There are solutions to assign certificates to a fleet of nodes, see an example.

Another option would be using IP certificates. They’re quite rare, and not a lot of CAs support generating them, but this might be worth investigating.

WebTransport

While WebSocket allows the browser to “hijack” a TCP connection, WebTransport does the same thing with a QUIC connection.

The protocol is brand-new, in fact, there’s not even an RFC yet: It’s still under development by the IETF WebTransport Working Group and the W3C WebTransport Working Group.

WebTransport is interesting for libp2p, because in contrast with WebSocket, there's a way around the strict certificate requirements, allowing the use in a p2p setting.

WebTransport Upgrade
Certificate Hashes
Securing the WebTransport Connection
Counting Round Trips

WebTransport Upgrade

The browser first establishes a HTTP/3 connection to the server. It then opens a new stream, and sends an Extended CONNECT request, and proposed a WebTransport Session ID.

The server can accept the upgrade by sending a HTTP 200 OK response. Both endpoints can now open QUIC streams associated with this WebTransport session.

HEADERS
method: CONNECT
protocol: webtransport
scheme: https
authority: https://chat.example.com
path: /chat
Origin: mywebsite.com

Certificate Hashes

In WebTransport, the browser has two ways to verify the TLS certificate:

Checking if the certificate is signed by a certificate authority (CA). The requirements are analogous to WebSocket Secure.
Checking that the SHA-256 hash of the certificate matches a pre-determined value.

The first options comes with the same problems that we encountered for WebSocket: libp2p nodes usually neither have a domain name, nor do they have an easy way to obtain a certificate from a CA.

libp2p makes use of the second option. We can encode the certificate hash into the multiaddress of a node, for example: /ip4*/1.2.3.4**/udp**/4001**/quic**/webtransport**/certhash**/<hash>*. The browser now knows the hash, and can establish a (secure!) connection.

Securing the WebTransport Connection

What does the certificate hash actually secure? By itself, not much. In particular, an attacker could have injected a multiaddress containing the hash of its own certificate. Furthermore, after completing the WebTransport handshake, the server doesn’t have any way to know the client’s peer ID.

libp2p therefore runs a Noise handshake on top of the first WebTransport stream. This handshake serves two purposes:

It exchanges and cryptographically verifies the peer IDs of the endpoints.
It binds the certificate hash to the WebTransport session, making sure there’s no MITM attack.

This handshake is only run on a single stream. As soon as the handshake completes, we can use raw WebTransport streams in libp2p - there is no need for any double encryption.

Counting Round Trips

QUIC Handshake (1 RTT)
WebTransport Upgrade (1 RTT)
Noise Handshake (1 RTT)

This is a lot faster than the WebSocket handshake!

Step 2 and 3 can potentially be run in parallel, although a bug in Chrome’s WebTransport implementation currently forces sequential execution.

Support

Possible

Chrome

Not Possible

node.js-libp2p

Work In Progress

go-libp2p
Firefox
Safari

Work Not Started

rust-libp2p

Get Involved

This is a very new protocol, and we can use your help.

Specification

Go implementation

Browser ⇄ Browser

WebRTC

Usually used for video conferencing, WebRTC is a suite of protocols that allows browsers to connect to servers, and to other browsers, and even punch through NATs.

In addition to enabling audio and video communication (for which packets are sent using an unreliably transport), WebRTC also establishes stream-based communication and exposes reliable streams, called WebRTC Data Channels.

Connection Establishment
Browser to Standalone Node
Browser to Browser
Securing the WebRTC Connection
Counting Roundtrips

Connection Establishment

In order to connect, two WebRTC nodes need to exchange SDP (Session Description Protocol) packets. These packets contain all the information that’s needed to establish the connection: (public) IP addresses, supported WebRTC features, audio and video codecs etc.

WebRTC specifies the format of this packet, but it doesn’t specify how they are exchanged. This is left to the application, or libp2p in our case.

Browser to Standalone Node

This is useful in cases where WebSocket and WebTransport are not available. In this case, we don't need to actually exchange the SDP, but only pretend that we did that, and actually construct the SDP from the node's advertised multiaddress(es). This saves one round-trip.

Browser to Browser

Connection one browser to another browser usually requires hole punching, as browsers are usually used by people in their home or corporate networks (i.e. behind their home router or a corporate firewall, respectively), or on mobile devices (i.e. behind a carrier-grade NAT).

Fortunately, WebRTC was built exactly for this use case, and provides hole-punching capabilites using the ICE protocol. The browser's WebRTC stack will handle this for us, as long as we manage to exchange the SDP in the first place. We use a special WebRTC coordination protocol run over relayed connections to do that.

In order to establish a relayed connection, we first need to connect to a relay node. Since the relay server will be a public node, we can use WebSocket, WebTransport or WebRTC for that purpose.

Securing the WebRTC Connection

As WebRTC is built to facilitate video conferencing between browsers, browsers accept self-signed certificates by default. However, they don’t provide any way to encode any additional information (like the libp2p peer identity) into the certificate, thus libp2p nodes need to run a second handshake on top of a WebRTC stream, similar to WebTransport.

Counting Roundtrips

For the browser to public node use case:

Establishing the WebRTC connection: 1 RTT, plus the time STUN takes
libp2p handshake (1 RTT)

For the browser to browser use case:

Establishing a connection to the relay: 2 - 3 RTTs (when using WebTransport or WebRTC), 6 RTTs (when using WebSocket)
Establishing a connection to the remote node via the relay (1 RTT)
Establishing the WebRTC connection: 1 RTT, plus the time STUN takes
libp2p handshake (1 RTT)

Support

Work In Progress

go-libp2
rust-libp2
js-libp2p

Get Involved

https://github.com/libp2p/specs/pull/412

Go implementation

Rust implementation

Made with love by Protocol Labs