From 76ccc4fabb7b8cd69760dacc186a7603d4f742dc Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Thu, 5 Jan 2023 14:53:35 -0800 Subject: [PATCH] add a basic QUIC spec (#499) * add a basic QUIC spec * fix spec status Co-authored-by: Max Inden * specify ALPN and link to libp2p TLS * add link to QUIC spec to README Co-authored-by: Max Inden --- README.md | 2 ++ quic/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 quic/README.md diff --git a/README.md b/README.md index 08087a9..64764ef 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,7 @@ The protocols described below all use [protocol buffers](https://developers.goog peer discovery - [secio][spec_secio] - SECIO, a transport security protocol for libp2p - [tls][spec_tls] - The libp2p TLS Handshake (TLS 1.3+) +- [quic][spec_quic] - The libp2p QUIC Handshake - [webrtc][spec_webrtc] - The libp2p WebRTC transport - [WebTransport][spec_webtransport] - Using WebTransport in libp2p @@ -122,6 +123,7 @@ you feel an issue isn't the appropriate place for your topic, please join our [spec_rendezvous]: ./rendezvous/README.md [spec_secio]: ./secio/README.md [spec_tls]: ./tls/tls.md +[spec_quic]: ./quic/README.md [spec_peerids]: ./peer-ids/peer-ids.md [spec_connections]: ./connections/README.md [spec_plaintext]: ./plaintext/README.md diff --git a/quic/README.md b/quic/README.md new file mode 100644 index 0000000..eb16284 --- /dev/null +++ b/quic/README.md @@ -0,0 +1,52 @@ +# QUIC in libp2p + +| Lifecycle Stage | Maturity | Status | Latest Revision | +|-----------------|---------------|--------|-----------------| +| 3A | Recommendation | Active | r1, 2022-12-30 | + +Authors: [@marten-seemann] + +Interest Group: [@elenaf9], [@MarcoPolo] + +[@marten-seemann]: https://github.com/marten-seemann +[@elenaf9]: https://github.com/elenaf9 +[@MarcoPolo]: https://github.com/MarcoPolo + +See the [lifecycle document][lifecycle-spec] for context about the maturity level +and spec status. + +[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md + +## QUIC vs. TCP + +QUIC [RFC9000] is, alongside TCP, one of the transports that allows non-browser libp2p nodes to establish connections to each other. +Due to its inherently faster handshake latency (a single network-roundtrip), and generally better performance characteristics, it is RECOMMENDED that libp2p implementations offer QUIC as one of their transports. +However, UDP is blocked in a small fraction of networks, therefore it is RECOMMENDED that libp2p nodes offer a TCP-based connection option as a fallback. + +### Multiaddress + +A QUIC multiaddress encodes the IP address and UDP port. For example, these are valid QUIC multiaddresses: +* `/ip4/127.0.0.1/udp/1234/quic-v1`: A QUIC listener running on localhost on port 1234. +* `/ip6/2001:db8:3333:4444:5555:6666:7777:8888/udp/443/quic-v1`: A QUIC listener running on 2001:db8:3333:4444:5555:6666:7777:8888 on port 443. +* `/ip4/12.34.56.78/udp/4321/quic`: A QUIC listener, supporting QUIC draft-29 (see below) + +### QUIC Versions + +When IPFS first rolled out QUIC support, RFC 9000 was not finished yet. Back then, QUIC was rolled out based on [IETF QUIC working group draft-29]. +Nodes supporting draft-29 use the `/quic` multiaddress component (instead of `/quic-v1`) to signal support for the draft version. +Nodes supporting RFC 9000 use the `/quic-v1` multiaddress component. + +New implementations SHOULD implement support for RFC 9000. Support for draft-29 is currently being phased out of production networks, and will be deprecated at some point in the future. + +### ALPN + +"libp2p" is used as the application protocol for ALPN. +Note that QUIC enforces the use of ALPN, so the handshake will fail if both peers can't agree on the application protocol. + +### Peer Authentication + +Peers authenticate each other using the TLS handshake logic described in the [libp2p TLS spec]. + +[RFC9000]: https://datatracker.ietf.org/doc/html/rfc9000 +[IETF QUIC working group draft-29]: https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-29 +[libp2p TLS spec]: ../tls