libp2p Connectivity

Standalone ⇄ Standalone
Browser to Standalone
Browser ⇄ Browser

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

libp2p Connectivity

Depending on their positions in the network, nodes use different technology to connect to other nodes.

Learn more about how libp2p achieves universal connectivity across networks.

Chat With Developers

Standalone Node ⇄ Standalone Node

Public nodes is any node running in a data centers, or on a dedicated connection without any router / NAT / firewall in between.

Full nodes (e.g. go-libp2p, rust-libp2p, node.js-libp2p) use TCP and QUIC to connect to each other.

TCP

TCP is a...

TCP in libp2p
Counting Round Trips
Support

TCP in libp2p

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

establish a TCP connection to the remote node
negotiate a security protocol (Noise or TLS 1.3), perform a cryptographic handshake. The connection is now encrypted and the peer IDs have been verified.
apply a stream multiplexer (yamux or mplex).

TCP is a solid option, works in all networks (home and private). However, setting up a the libp2p takes quite a few network roundtrips.

Counting Round Trips

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

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

Support

go-libp2p: ✔

rust-libp2p: ✔

node.js-libp2p: ✔

Chrome: ❌ (not possible)

Firefox: ❌ (not possbile)

Safari: ❌ (not possible)

QUIC

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

Whenever possible, QUIC should be preferred over TCP. For more benefits of using QUIC, see #holepunching.

However: UDP is blocked in ~5-10% of networks. Therefore TCP is still needed as a fallback.

QUIC in libp2p
Counting Round Trips
Support

QUIC in libp2p

Under most conditions, QUIC provides superior performance to TCP: The libp2p handshake is (at least!) 3 network round-trips faster, and provides better performance in unstable network conditions.

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

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

go-libp2p: ✔

rust-libp2p: ⏱ (work in progress)

node.js-libp2p: ❌

Chrome: ❌ (not possible)

Firefox: ❌ (not possible)

Safari: ❌ (not possible)

Hole Punching

Not all nodes are located in a publicly reachable position. Most nodes are behind NATs or firewalls: in home networks, in corporate networks, and even on mobile devices (carrier-grade NATs).

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

libp2p Relays
Obtaining a Direct Connection
Support
Further Reading

libp2p Relays

When a libp2p node boots up, one of the first things it does it 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

go-libp2p: ✔

rust-libp2p: ✔

node.js-libp2p: ✔

Browser → Standalone Node

We want to be able to access the libp2p network from a web browser. Browsers are really, really good at speaking HTTP (using an underlying TCP connection for HTTP/1.1 and HTTP/2, and a QUIC connection for HTTP/3), but they don't allow access to the underlying connection.

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 deals with streams. 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 has been around for more than 10 years. It allows “hijacking” of a HTTP/1.1 connection (it was later also standardized for HTTP/2), giving the browser access to the underlying TCP connection.

WebSocket Upgrade
Code
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: GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade The server can accept this upgrade request by sending a HTTP 200 response. All bytes sent on the TCP connection after this are now

Code

const socket = new WebSocket('ws://chat.example.com/chat');
// TODO: show how to send some and receive some data

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 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.

WebSocket Secure is Websocket that doesn’t use HTTP, but HTTPS, to do the Upgrade request. That means that in addition to the 5 round trips listed above, there’ll be another roundtrip for the TLS handshake.

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 wants to impersonate libp2p.io, she can just sign her own certificate. Browsers are shipped with a list of signatories, called Certificate Authorities (CA) that they trust. The most widely used CA on the internet is LetsEncrypt.

This is a problem for libp2p. Most nodes on the network don’t even have a domain name, let alone a (CA-signed) certificate. Nodes that do can already configure WebSocket Secure in their libp2p node, but only very few nodes.

ACME to the rescue?

The ACME protocol allows a server to obtain a certificate from a CA fully automatically. 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 (pseudo-) random value on the website. It then makes a request to that website, and checks the value. The server is only able to publish the value if it actually controls the contents of the website.
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. DNS challenges are the only way to obtain wildcard certificates.

There are a couple of problems with this approach:

libp2p nodes still need to possess a domain name.
Using the HTTP / TLS challenge requires starting a webserver on port 80 or 443. On Linux, a non-privileged user is not able to bind to port smaller than 1024. It might also conflict with other processes that are listening on said ports.
The DNS challenge requires (programmatic) access to the DNS records for the domain. This is not possible without special configuration.

Support

go-libp2p: ✔

rust-libp2p: ✔

node.js-libp2p: ???

Chrome: ✔

Firefox: ✔

Safari: ✔

Get involved!

There are solutions to assign certificates to a fleet of nodes, see for example https://words.filippo.io/how-plex-is-doing-https-for-all-its-users/.

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 WebSockets 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 Upgrade
Code
Securing the WebTransport Connection
Counting Round Trips

WebTransport Upgrade

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

HEADERS

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

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

Code

Similar to how QUIC shines over TCP, WebTransport should be preferred over WebSocket. But for libp2p, there’s one more reason to use WebTransport instead of WebSocket. As we’ve seen above, browsers enforce secure WebSocket connections when the website is loaded via HTTPS, and this is no different when using WebTransport.

const conf = { "serverCertificateHashes": [ { "algorithm": "sha-256", "value": hash1, } ] }

const transport = new WebTransport('https://chat.example.com/chat', conf)

// TODO: show how to open / accept streams and how to send data

Securing the WebTransport Connection

What does the certificate hash secure? By itself, not much. In particular, the server doesn’t have any way to know the client’s peer ID.

We therefore run a Noise handshake on top of the first WebTransport stream. This handshake does two things:

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.

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

go-libp2p: ⏱ (work in progress)

rust-libp2p: ❌

node.js-libp2p: ❌

Chrome: ✔️

Firefox: ⏱ (work in progress, TODO: link to issue)

Safari: ❌ (status unknown)

Get Involved

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

Specification: https://github.com/libp2p/specs/pull/404

Go implementation: https://github.com/marten-seemann/webtransport-go

Browser ⇄ Browser

Some content here?

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 on top of SCTP and exposes reliable streams, called WebRTC Data Channels.

Connection Establishment
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.

There are two distinct use cases here.

Browser to Public 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

go-libp2p: working on the implementation

rust-libp2p: working on the implementation

js-libp2p: working on the implementation

Get involved

https://github.com/libp2p/specs/pull/412
Go implementation
Rust implementation

Made with love by Protocol Labs