From fba76c4850bdb88f57e747a7bea5caba43083110 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Mon, 4 Apr 2022 11:04:42 +0100 Subject: [PATCH 01/25] add a draft for the WebTransport spec --- webtransport/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 webtransport/README.md diff --git a/webtransport/README.md b/webtransport/README.md new file mode 100644 index 000000000..20a8733ed --- /dev/null +++ b/webtransport/README.md @@ -0,0 +1,52 @@ +# libp2p WebTransport + +| Lifecycle Stage | Maturity | Status | Latest Revision | +|-----------------|--------------------------|--------|-----------------| +| 1A | DRAFT | Active | r0, 2022-04-03 | + +Authors: [@marten-seemann] + +Interest Group: TODO + +See the [lifecycle document][lifecycle-spec] for context about maturity level +and spec status. + +## Introduction + +WebTransport is a way for browsers to establish a stream-multiplexed connection to servers that allows bidirectional streaming. + +The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). + +The most exciting feature for libp2p (other than the improved performance and hole punching success rates that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: `[serverCertificateHashes](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes)`. This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. + +## Certificates + +Server nodes can choose between 2 modes of operation: +1. They possess a certificate that's accepted by the WebPKI (i.e. a certificate signed by a well-known certificate authority). Due to the p2p nature of libp2p, obtaining such a certificate will only be practical for a small number of nodes. +2. They use a self-signed certificate. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days. Nodes then include the hash of one (or more) certificates in their multiaddr (see [#addressing]). + +When using self-signed certificates, nodes need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates a self-signed certificate with a validity of 14 days, and publishes a multiaddr containing the hash of that certificate. After 10 days, the node prepares the next certificate, setting the `NotBefore` date of that certificate to the expiration date (or shortly before that) of the first certificate, and an expiration of 14 days after that. The node continues using the old certificate until its expiry date, but it already advertises a multiaddr containing both certificate hashes. This way, clients will be able to connect to the node, even if they cache the multiaddr for multiple days. + +## Addressing + +Webtransport multiaddresses are composed of a QUIC multiaddr, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. +Examples: +* `/ip4/1.2.3.4/udp/443/quic/webtransport/` +* `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/` + +If it is able to present a CA-signed certificate the list of certificate hashes SHOULD be empty. When using self-signed certificates, the server MUST include the hash(es) in the multiaddr. + +## Security Handshake + +Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. +Once a WebTransport session is established, the clients opens a new stream and initiates a libp2p handshake (selecting the security protocol by running multistream, then performing the selected handshake). + +Note: Once we include the security protocol in the multiaddr (see https://github.com/libp2p/specs/pull/353), we will be able to shave off two (!!) round-trips here: Not running multistream saves one round trip. Furthermore, we'll be able to run the WebTransport handshake (i.e. the CONNECT request) in parallel with the cryptographic handshake, for example by transmitting the first handshake message as a URL parameter. The specifics of this is left to a future iteration of this spec. + +## Securing Streams + +All streams other than the stream used for the security handshake are protected using Salsa20. Two (symmetric) keys are derived from the master secrect established during the handshake, one for sending and for receiving on the stream. + +When using TLS, the 32 byte key used by Salsa20 is derived using the algorithm described in RFC 5705. In Go, this is achieved by using [`tls.ConnectionState.ExportKeyingMaterial`](https://pkg.go.dev/crypto/tls#ConnectionState.ExportKeyingMaterial). The label is `libp2p-webtransport-stream-`, where `` is `client` or `server`, respectively, depending on which side is sending on the stream, and the context is the QUIC stream ID, serialized as a uint64 in network byte order. + +TODO: We need a similar construction for Noise. From fc10260e8187fd8ceb66be6eaae0c954adf45fd1 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Mon, 4 Apr 2022 11:13:35 +0100 Subject: [PATCH 02/25] describe the HTTP endpoint --- webtransport/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/webtransport/README.md b/webtransport/README.md index 20a8733ed..c6348ecb0 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -36,6 +36,14 @@ Examples: If it is able to present a CA-signed certificate the list of certificate hashes SHOULD be empty. When using self-signed certificates, the server MUST include the hash(es) in the multiaddr. +## WebTransport HTTP endpoint + +WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport servers MUST be located at `/.well-known/libp2p-webtransport`. + +To allow future evolution of the way we run the libp2p handshake over WebTransport, we use a URL parameter. The handshake described in this document MUST be signaled by setting the `type` URL parameter to `multistream`. + +Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4/udp/1443/quic/webtransport/` would be `https://1.2.3.4:1443/.well-known/libp2p-webtransport?type=multistream`. + ## Security Handshake Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. From 48dda39d67987e7a6f98f0f56284b5a4b9a1148f Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 6 Apr 2022 03:51:03 -0700 Subject: [PATCH 03/25] improve introduction Co-authored-by: Melanie Riise --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index c6348ecb0..2e76e46ba 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -13,7 +13,7 @@ and spec status. ## Introduction -WebTransport is a way for browsers to establish a stream-multiplexed connection to servers that allows bidirectional streaming. +WebTransport is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers using QUIC. The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). From 1e927c41ca6a7fb69b336cdb6f564f41ad94aeca Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Sun, 17 Apr 2022 19:58:58 +0100 Subject: [PATCH 04/25] use Noise to check end-to-end encryption of the WebTransport connection --- webtransport/README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 2e76e46ba..10d0a799d 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -40,21 +40,18 @@ If it is able to present a CA-signed certificate the list of certificate hashes WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport servers MUST be located at `/.well-known/libp2p-webtransport`. -To allow future evolution of the way we run the libp2p handshake over WebTransport, we use a URL parameter. The handshake described in this document MUST be signaled by setting the `type` URL parameter to `multistream`. +To allow future evolution of the way we run the libp2p handshake over WebTransport, we use a URL parameter. The handshake described in this document MUST be signaled by setting the `type` URL parameter to `noise`. -Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4/udp/1443/quic/webtransport/` would be `https://1.2.3.4:1443/.well-known/libp2p-webtransport?type=multistream`. +Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4/udp/1443/quic/webtransport/` would be `https://1.2.3.4:1443/.well-known/libp2p-webtransport?type=noise`. ## Security Handshake Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. -Once a WebTransport session is established, the clients opens a new stream and initiates a libp2p handshake (selecting the security protocol by running multistream, then performing the selected handshake). +The first stream that the client opens on a new WebTransport session is used to perform a libp2p handshake using Noise (https://github.com/libp2p/specs/tree/master/noise). The client SHOULD start the handshake right after sending the CONNECT request, without waiting for the server's response. -Note: Once we include the security protocol in the multiaddr (see https://github.com/libp2p/specs/pull/353), we will be able to shave off two (!!) round-trips here: Not running multistream saves one round trip. Furthermore, we'll be able to run the WebTransport handshake (i.e. the CONNECT request) in parallel with the cryptographic handshake, for example by transmitting the first handshake message as a URL parameter. The specifics of this is left to a future iteration of this spec. +In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the client MUST include the certificate hash that was used to establish the connection as payload of the first Noise message (the `e` message). This payload is not encrypted, but the Noise handshake provides integrity protection. +If the client was willing to accept multiple certificate hashes, but cannot determine with certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST include a list of all certificate hashes. -## Securing Streams +On receipt of the `e` message, the server MUST verify the list of certificate hashes. If the list is empty, it MUST fail the handshake. For every certificate in the list, it checks if it possesses a certificate with the corresponding hash. If so, it continues with the handshake. However, if there is even a single certificate hash in the list that it cannot associate with a certificate, it MUST abort the handshake. -All streams other than the stream used for the security handshake are protected using Salsa20. Two (symmetric) keys are derived from the master secrect established during the handshake, one for sending and for receiving on the stream. - -When using TLS, the 32 byte key used by Salsa20 is derived using the algorithm described in RFC 5705. In Go, this is achieved by using [`tls.ConnectionState.ExportKeyingMaterial`](https://pkg.go.dev/crypto/tls#ConnectionState.ExportKeyingMaterial). The label is `libp2p-webtransport-stream-`, where `` is `client` or `server`, respectively, depending on which side is sending on the stream, and the context is the QUIC stream ID, serialized as a uint64 in network byte order. - -TODO: We need a similar construction for Noise. +For the client, the libp2p connection is fully established once it has sent the last Noise handshake message. For the server, receipt (and successful verification) of that message completes the handshake. From 0882c0317f15ebf71b497dcbd662986cfd33d344 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Sun, 17 Apr 2022 20:02:38 +0100 Subject: [PATCH 05/25] define protobuf to encode certificate hashes --- webtransport/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/webtransport/README.md b/webtransport/README.md index 10d0a799d..947078b29 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -52,6 +52,15 @@ The first stream that the client opens on a new WebTransport session is used to In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the client MUST include the certificate hash that was used to establish the connection as payload of the first Noise message (the `e` message). This payload is not encrypted, but the Noise handshake provides integrity protection. If the client was willing to accept multiple certificate hashes, but cannot determine with certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST include a list of all certificate hashes. +Certificate hashes are encoded using the following protobuf message: +```proto +syntax = "proto2"; + +message WebTransport { + repeated bytes cert_hashes = 1; +} +``` + On receipt of the `e` message, the server MUST verify the list of certificate hashes. If the list is empty, it MUST fail the handshake. For every certificate in the list, it checks if it possesses a certificate with the corresponding hash. If so, it continues with the handshake. However, if there is even a single certificate hash in the list that it cannot associate with a certificate, it MUST abort the handshake. For the client, the libp2p connection is fully established once it has sent the last Noise handshake message. For the server, receipt (and successful verification) of that message completes the handshake. From 72f6c15ca03fb0b70520cf67de41428b2b5d1c63 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Sun, 17 Apr 2022 20:10:36 +0100 Subject: [PATCH 06/25] use a separate multiaddr component for certificate hashes --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 947078b29..06d9c5a05 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -32,7 +32,7 @@ When using self-signed certificates, nodes need to take care to regularly renew Webtransport multiaddresses are composed of a QUIC multiaddr, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. Examples: * `/ip4/1.2.3.4/udp/443/quic/webtransport/` -* `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/` +* `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/certhash//certhash//certhash/` If it is able to present a CA-signed certificate the list of certificate hashes SHOULD be empty. When using self-signed certificates, the server MUST include the hash(es) in the multiaddr. From 599b3f4f0dcaf563d323055aa27f6d0c1c3dabf4 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Sun, 17 Apr 2022 20:21:56 +0100 Subject: [PATCH 07/25] remove server mode using CA signed certificates --- webtransport/README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 06d9c5a05..0edb9ae87 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -21,21 +21,17 @@ The most exciting feature for libp2p (other than the improved performance and ho ## Certificates -Server nodes can choose between 2 modes of operation: -1. They possess a certificate that's accepted by the WebPKI (i.e. a certificate signed by a well-known certificate authority). Due to the p2p nature of libp2p, obtaining such a certificate will only be practical for a small number of nodes. -2. They use a self-signed certificate. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days. Nodes then include the hash of one (or more) certificates in their multiaddr (see [#addressing]). +Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [#addressing]). -When using self-signed certificates, nodes need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates a self-signed certificate with a validity of 14 days, and publishes a multiaddr containing the hash of that certificate. After 10 days, the node prepares the next certificate, setting the `NotBefore` date of that certificate to the expiration date (or shortly before that) of the first certificate, and an expiration of 14 days after that. The node continues using the old certificate until its expiry date, but it already advertises a multiaddr containing both certificate hashes. This way, clients will be able to connect to the node, even if they cache the multiaddr for multiple days. +Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates a self-signed certificate with a validity of 14 days, and publishes a multiaddr containing the hash of that certificate. After 10 days, the node prepares the next certificate, setting the `NotBefore` date of that certificate to the expiration date (or shortly before that) of the first certificate, and an expiration of 14 days after that. The node continues using the old certificate until the expiry date, but it already advertises a multiaddr containing both certificate hashes. This way, clients will be able to connect to the node, even if they cache the multiaddr for multiple days. ## Addressing Webtransport multiaddresses are composed of a QUIC multiaddr, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. Examples: -* `/ip4/1.2.3.4/udp/443/quic/webtransport/` +* `/ip4/1.2.3.4/udp/443/quic/webtransport/certhash/` * `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/certhash//certhash//certhash/` -If it is able to present a CA-signed certificate the list of certificate hashes SHOULD be empty. When using self-signed certificates, the server MUST include the hash(es) in the multiaddr. - ## WebTransport HTTP endpoint WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport servers MUST be located at `/.well-known/libp2p-webtransport`. From 243fd0484fc242967e4c4aaa72a4dfc1b6c71807 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Mon, 27 Jun 2022 02:33:21 -0700 Subject: [PATCH 08/25] apply suggestions from code review Co-authored-by: Marcin Rataj Co-authored-by: Max Inden --- webtransport/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 0edb9ae87..96304a3c6 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -8,7 +8,7 @@ Authors: [@marten-seemann] Interest Group: TODO -See the [lifecycle document][lifecycle-spec] for context about maturity level +See the [lifecycle document](../00-framework-01-spec-lifecycle.md) for context about maturity level and spec status. ## Introduction @@ -17,11 +17,11 @@ WebTransport is a way for browsers to establish a stream-multiplexed and bidirec The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). -The most exciting feature for libp2p (other than the improved performance and hole punching success rates that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: `[serverCertificateHashes](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes)`. This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. +The most exciting feature for libp2p (other than the improved performance and hole punching success rates that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. ## Certificates -Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [#addressing]). +Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates a self-signed certificate with a validity of 14 days, and publishes a multiaddr containing the hash of that certificate. After 10 days, the node prepares the next certificate, setting the `NotBefore` date of that certificate to the expiration date (or shortly before that) of the first certificate, and an expiration of 14 days after that. The node continues using the old certificate until the expiry date, but it already advertises a multiaddr containing both certificate hashes. This way, clients will be able to connect to the node, even if they cache the multiaddr for multiple days. @@ -46,7 +46,7 @@ Unfortunately, the self-signed certificate doesn't allow the nodes to authentica The first stream that the client opens on a new WebTransport session is used to perform a libp2p handshake using Noise (https://github.com/libp2p/specs/tree/master/noise). The client SHOULD start the handshake right after sending the CONNECT request, without waiting for the server's response. In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the client MUST include the certificate hash that was used to establish the connection as payload of the first Noise message (the `e` message). This payload is not encrypted, but the Noise handshake provides integrity protection. -If the client was willing to accept multiple certificate hashes, but cannot determine with certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST include a list of all certificate hashes. +If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST include a list of all certificate hashes. Certificate hashes are encoded using the following protobuf message: ```proto From 2cec2b3af68522d1a214bee932750a81e8bd2815 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Tue, 20 Sep 2022 21:35:50 +0300 Subject: [PATCH 09/25] webtransport: move certhash verification to the client (#455) --- webtransport/README.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 96304a3c6..1b172ae99 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -45,18 +45,8 @@ Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4 Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. The first stream that the client opens on a new WebTransport session is used to perform a libp2p handshake using Noise (https://github.com/libp2p/specs/tree/master/noise). The client SHOULD start the handshake right after sending the CONNECT request, without waiting for the server's response. -In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the client MUST include the certificate hash that was used to establish the connection as payload of the first Noise message (the `e` message). This payload is not encrypted, but the Noise handshake provides integrity protection. -If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST include a list of all certificate hashes. +In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the server MUST include the certificate hash of the currently used certificate as well as the certificate hashes of all future certificates it has already advertised to the network in the `webtransport_certhashes` Noise extension. The hash of recently used, but expired certificates SHOULD also be included. -Certificate hashes are encoded using the following protobuf message: -```proto -syntax = "proto2"; - -message WebTransport { - repeated bytes cert_hashes = 1; -} -``` - -On receipt of the `e` message, the server MUST verify the list of certificate hashes. If the list is empty, it MUST fail the handshake. For every certificate in the list, it checks if it possesses a certificate with the corresponding hash. If so, it continues with the handshake. However, if there is even a single certificate hash in the list that it cannot associate with a certificate, it MUST abort the handshake. +On receipt of the `webtransport_certhashes` extension, the client MUST verify that the certificate hash of the certificate that was used on the connection is contained in the server's list. If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST verify that all certificate hashes are contained in the server's list. If verification fails, it MUST abort the handshake. For the client, the libp2p connection is fully established once it has sent the last Noise handshake message. For the server, receipt (and successful verification) of that message completes the handshake. From 36010745653930d75997625f4544ede02711f05f Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 22:38:59 +0300 Subject: [PATCH 10/25] webtransport: remove confusion around Noise handshake completion --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 1b172ae99..e71521488 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -49,4 +49,4 @@ In order to verify that the end-to-end encryption of the connection, the peers n On receipt of the `webtransport_certhashes` extension, the client MUST verify that the certificate hash of the certificate that was used on the connection is contained in the server's list. If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST verify that all certificate hashes are contained in the server's list. If verification fails, it MUST abort the handshake. -For the client, the libp2p connection is fully established once it has sent the last Noise handshake message. For the server, receipt (and successful verification) of that message completes the handshake. +For the client, the libp2p connection is fully established once it has sent the last Noise handshake message. For the server, processing of that message completes the handshake. From ee95b87392f8a7776898db219d7ac718c6200f4b Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 22:57:36 +0300 Subject: [PATCH 11/25] webtransport: update certificate generation logic --- webtransport/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index e71521488..08cc9e877 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -23,7 +23,8 @@ The most exciting feature for libp2p (other than the improved performance and ho Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). -Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates a self-signed certificate with a validity of 14 days, and publishes a multiaddr containing the hash of that certificate. After 10 days, the node prepares the next certificate, setting the `NotBefore` date of that certificate to the expiration date (or shortly before that) of the first certificate, and an expiration of 14 days after that. The node continues using the old certificate until the expiry date, but it already advertises a multiaddr containing both certificate hashes. This way, clients will be able to connect to the node, even if they cache the multiaddr for multiple days. +Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day valididity period starting on the expiry date of the first certificate. The node advertises a multiaddr containing the certificate hashes of these two certificates. +Once the first certificate has expired, the node prepares the next certificate, and updates the multiaddr it advertises. ## Addressing From df56a5ff27a249e6cc8b189c4758de3f0abf645a Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:06:09 +0300 Subject: [PATCH 12/25] webtransport: link to Noise Extensions spec --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 08cc9e877..373b8f616 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -46,7 +46,7 @@ Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4 Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. The first stream that the client opens on a new WebTransport session is used to perform a libp2p handshake using Noise (https://github.com/libp2p/specs/tree/master/noise). The client SHOULD start the handshake right after sending the CONNECT request, without waiting for the server's response. -In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the server MUST include the certificate hash of the currently used certificate as well as the certificate hashes of all future certificates it has already advertised to the network in the `webtransport_certhashes` Noise extension. The hash of recently used, but expired certificates SHOULD also be included. +In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the server MUST include the certificate hash of the currently used certificate as well as the certificate hashes of all future certificates it has already advertised to the network in the `webtransport_certhashes` Noise extension (see Noise Extension section of the [Noise spec](/noise/README.md)). The hash of recently used, but expired certificates SHOULD also be included. On receipt of the `webtransport_certhashes` extension, the client MUST verify that the certificate hash of the certificate that was used on the connection is contained in the server's list. If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST verify that all certificate hashes are contained in the server's list. If verification fails, it MUST abort the handshake. From 92e4635112a944d51ea49074b18a0fd011e213f7 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:08:41 +0300 Subject: [PATCH 13/25] webtransport: move spec to Candidate Recommendation --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 373b8f616..c9fd4e8db 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -2,7 +2,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|--------------------------|--------|-----------------| -| 1A | DRAFT | Active | r0, 2022-04-03 | +| 1A | Candidate Recommendation | Active | r0, 2022-09-28 | Authors: [@marten-seemann] From 76d721768d3d780ab60ef1d24134882d73c3fad8 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:09:50 +0300 Subject: [PATCH 14/25] webtransport: remove misleading mention of hole punching --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index c9fd4e8db..b677448ec 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -17,7 +17,7 @@ WebTransport is a way for browsers to establish a stream-multiplexed and bidirec The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). -The most exciting feature for libp2p (other than the improved performance and hole punching success rates that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. +The most exciting feature for libp2p (other than the numberous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. ## Certificates From afa554d9707a782d278d9b76154ae05cec699963 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:10:40 +0300 Subject: [PATCH 15/25] webtransport: fix typos --- webtransport/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index b677448ec..27c420177 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -35,7 +35,7 @@ Examples: ## WebTransport HTTP endpoint -WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport servers MUST be located at `/.well-known/libp2p-webtransport`. +WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport server MUST be located at `/.well-known/libp2p-webtransport`. To allow future evolution of the way we run the libp2p handshake over WebTransport, we use a URL parameter. The handshake described in this document MUST be signaled by setting the `type` URL parameter to `noise`. @@ -46,7 +46,7 @@ Example: The WebTransport URL of a WebTransport server advertising `/ip4/1.2.3.4 Unfortunately, the self-signed certificate doesn't allow the nodes to authenticate each others' peer IDs. It is therefore necessary to run an additional libp2p handshake on a newly established WebTransport connection. The first stream that the client opens on a new WebTransport session is used to perform a libp2p handshake using Noise (https://github.com/libp2p/specs/tree/master/noise). The client SHOULD start the handshake right after sending the CONNECT request, without waiting for the server's response. -In order to verify that the end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the server MUST include the certificate hash of the currently used certificate as well as the certificate hashes of all future certificates it has already advertised to the network in the `webtransport_certhashes` Noise extension (see Noise Extension section of the [Noise spec](/noise/README.md)). The hash of recently used, but expired certificates SHOULD also be included. +In order to verify end-to-end encryption of the connection, the peers need to establish that no MITM intercepted the connection. To do so, the server MUST include the certificate hash of the currently used certificate as well as the certificate hashes of all future certificates it has already advertised to the network in the `webtransport_certhashes` Noise extension (see Noise Extension section of the [Noise spec](/noise/README.md)). The hash of recently used, but expired certificates SHOULD also be included. On receipt of the `webtransport_certhashes` extension, the client MUST verify that the certificate hash of the certificate that was used on the connection is contained in the server's list. If the client was willing to accept multiple certificate hashes, but cannot determine which certificate was actually used to establish the connection (this will commonly be the case for browser clients), it MUST verify that all certificate hashes are contained in the server's list. If verification fails, it MUST abort the handshake. From 1942361cd0ddcd3b92113301eb97524797cff825 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:13:09 +0300 Subject: [PATCH 16/25] webtransport: add interest group --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 27c420177..2e83ed161 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -6,7 +6,7 @@ Authors: [@marten-seemann] -Interest Group: TODO +Interest Group: [@MarcoPolo], [@mxinden] See the [lifecycle document](../00-framework-01-spec-lifecycle.md) for context about maturity level and spec status. From f968d72fe8c116c1800ab69c8512c9a08c837a79 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 28 Sep 2022 23:16:40 +0300 Subject: [PATCH 17/25] webtransport: add link to Firefox meta-issue --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 2e83ed161..eec514c72 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -15,7 +15,7 @@ and spec status. WebTransport is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers using QUIC. -The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). +The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/), and Firefox [is working](https://bugzilla.mozilla.org/show_bug.cgi?id=1709355) on WebTransport support. The most exciting feature for libp2p (other than the numberous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. From 5ab529dce7e71fe9471471c099a08e61ea31390d Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 11:38:51 +0300 Subject: [PATCH 18/25] webtransport: soften language around URL multiaddr encoding --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index eec514c72..ad33425fa 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -35,7 +35,7 @@ Examples: ## WebTransport HTTP endpoint -WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. As multiaddrs don't allow the encoding of URLs, this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport server MUST be located at `/.well-known/libp2p-webtransport`. +WebTransport needs a HTTPS URL to establish a WebTransport session, e.g. `https://example.com/webtransport`. At the point of writing multiaddresses don't allow the encoding of URLs, therefore this spec standardizes the endpoint. The HTTP endpoint of a libp2p WebTransport server MUST be located at `/.well-known/libp2p-webtransport`. To allow future evolution of the way we run the libp2p handshake over WebTransport, we use a URL parameter. The handshake described in this document MUST be signaled by setting the `type` URL parameter to `noise`. From 1219d072120004bf5c7c644ee2b1e22d619a45f3 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 11:45:55 +0300 Subject: [PATCH 19/25] webtransport: clarify that WebTransport over HTTP/3 is meant --- webtransport/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index ad33425fa..37b7a6475 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -13,9 +13,11 @@ and spec status. ## Introduction -WebTransport is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers using QUIC. +[WebTransport](https://datatracker.ietf.org/doc/draft-ietf-webtrans-overview/) is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers. The WebTransport protocol is currently under development at the IETF. The primary way to do by running on top of a HTTP/3 connection [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). For situations where it is not possible to establish a HTTP/3 connection, there's a HTTP/2 fallback ([WebTransport using HTTP/2](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http2/)). -The WebTransport protocol is currently under development at the IETF. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/), and Firefox [is working](https://bugzilla.mozilla.org/show_bug.cgi?id=1709355) on WebTransport support. +In this document, we mean WebTransport over HTTP/3 when using the term WebTransport. + +Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/02/), and Firefox [is working](https://bugzilla.mozilla.org/show_bug.cgi?id=1709355) on WebTransport support. The most exciting feature for libp2p (other than the numberous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. From 4f498a1ce6ccff8a8b4729800ebd42ab11113328 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 01:49:59 -0700 Subject: [PATCH 20/25] webtransport: fix typo Co-authored-by: Elena Frank --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index 37b7a6475..b109cdf90 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -19,7 +19,7 @@ In this document, we mean WebTransport over HTTP/3 when using the term WebTransp Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/02/), and Firefox [is working](https://bugzilla.mozilla.org/show_bug.cgi?id=1709355) on WebTransport support. -The most exciting feature for libp2p (other than the numberous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. +The most exciting feature for libp2p (other than the numerous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. ## Certificates From 53d98bdb94cf714d8fe58c68c77e1882cff18dc3 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 11:50:59 +0300 Subject: [PATCH 21/25] webtransport: clarify certificate regeneration logic --- webtransport/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/webtransport/README.md b/webtransport/README.md index b109cdf90..481930ecb 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -26,7 +26,7 @@ The most exciting feature for libp2p (other than the numerous performance benefi Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day valididity period starting on the expiry date of the first certificate. The node advertises a multiaddr containing the certificate hashes of these two certificates. -Once the first certificate has expired, the node prepares the next certificate, and updates the multiaddr it advertises. +Once the first certificate has expired, the node starts using the already generated next certificate. At the same time, it again generates a new certificate for the following period and updates the multiaddress it advertises. ## Addressing From 527113589465d914f581c86fc2c932b71933d725 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 01:52:28 -0700 Subject: [PATCH 22/25] webtransport: fix typos Co-authored-by: Elena Frank --- webtransport/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 481930ecb..95348ecc2 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -25,12 +25,12 @@ The most exciting feature for libp2p (other than the numerous performance benefi Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). -Servers need to take care to regularly renew their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day valididity period starting on the expiry date of the first certificate. The node advertises a multiaddr containing the certificate hashes of these two certificates. +Servers need to take care of regularly renewing their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day validity period starting on the expiry date of the first certificate. The node advertises a multiaddress containing the certificate hashes of these two certificates. Once the first certificate has expired, the node starts using the already generated next certificate. At the same time, it again generates a new certificate for the following period and updates the multiaddress it advertises. ## Addressing -Webtransport multiaddresses are composed of a QUIC multiaddr, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. +WebTransport multiaddresses are composed of a QUIC multiaddress, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. Examples: * `/ip4/1.2.3.4/udp/443/quic/webtransport/certhash/` * `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/certhash//certhash//certhash/` From bb90d58762074f3042558b69e91cb0a6a6fdc5a9 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 30 Sep 2022 12:06:07 +0300 Subject: [PATCH 23/25] webtransport: allow use of CA-signed certificates --- webtransport/README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 95348ecc2..b62a5efa7 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -23,9 +23,17 @@ The most exciting feature for libp2p (other than the numerous performance benefi ## Certificates -Since most libp2p nodes don't possess a TLS certificate signed by a Certificate Authority, servers use a self-signed certificates. According to the [w3c WebTransport certification](https://www.w3.org/TR/webtransport/), the validity of the certificate MUST be at most 14 days, and must not use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). +According to the [w3c WebTransport specification](https://www.w3.org/TR/webtransport/), there are two ways for browser to validate the certificate used on a WebTransport connection. +1. by verifying the chain of trust of the certificate. This means that the certificate has to be signed by a CA (Certificate Authority) that the browser trusts. This is how browsers verify certificates when establishing a regular HTTPS connection. +2. by verifying that the cryptographic hash of the certificate matches a specific value, using the [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes) option. -Servers need to take care of regularly renewing their certificate. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day validity period starting on the expiry date of the first certificate. The node advertises a multiaddress containing the certificate hashes of these two certificates. +libp2p nodes that possess a CA-signed TLS certificate MAY use that certificate on WebTransport connections. + +The rest of this section applies to nodes that wish to use self-signed certificates and make use of the verification by certificate hash. + +According to the w3c specification, the validity of the certificate MUST be at most 14 days, and MUST NOT use an RSA key. Nodes then include the hash of one (or more) certificates in their multiaddr (see [Addressing](#addressing)). + +Servers need to take care of regularly renewing their certificates. In the following, the RECOMMENDED logic for rolling certificates is described. At first boot of the node, it creates one self-signed certificate with a validity of 14 days, starting immediately, and another certificate with the 14 day validity period starting on the expiry date of the first certificate. The node advertises a multiaddress containing the certificate hashes of these two certificates. Once the first certificate has expired, the node starts using the already generated next certificate. At the same time, it again generates a new certificate for the following period and updates the multiaddress it advertises. ## Addressing From f9f8613ea02191c03a5e0f4115a65fe6e09cf6d4 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 12 Oct 2022 21:06:49 +0200 Subject: [PATCH 24/25] address minor issues raised in code review --- webtransport/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index b62a5efa7..0010eca19 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -13,17 +13,17 @@ and spec status. ## Introduction -[WebTransport](https://datatracker.ietf.org/doc/draft-ietf-webtrans-overview/) is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers. The WebTransport protocol is currently under development at the IETF. The primary way to do by running on top of a HTTP/3 connection [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). For situations where it is not possible to establish a HTTP/3 connection, there's a HTTP/2 fallback ([WebTransport using HTTP/2](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http2/)). +[WebTransport](https://datatracker.ietf.org/doc/draft-ietf-webtrans-overview/) is a way for browsers to establish a stream-multiplexed and bidirectional connection to servers. The WebTransport protocol is currently under development at the IETF. The primary way to do this is by running on top of a HTTP/3 connection [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). For situations where it is not possible to establish a HTTP/3 connection (e.g. when UDP is blocked), there's a HTTP/2 fallback ([WebTransport using HTTP/2](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http2/)). In this document, we mean WebTransport over HTTP/3 when using the term WebTransport. Chrome has implemented and shipped support for [draft-02](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/02/), and Firefox [is working](https://bugzilla.mozilla.org/show_bug.cgi?id=1709355) on WebTransport support. -The most exciting feature for libp2p (other than the numerous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576). Firefox is working on a WebTransport implementation and is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) `serverCertificateHashes` as well. +The most exciting feature for libp2p (other than the numerous performance benefits that QUIC gives us) is that the W3C added a browser API allowing browsers to establish connections to nodes with self-signed certificates, provided they know the hash of the certificate in advance: [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes). This API is already [implemented in Chrome](https://chromestatus.com/feature/5690646332440576), and Firefox is [likely to implement](https://github.com/mozilla/standards-positions/issues/167#issuecomment-1015951396) this part of the specification as well. ## Certificates -According to the [w3c WebTransport specification](https://www.w3.org/TR/webtransport/), there are two ways for browser to validate the certificate used on a WebTransport connection. +According to the [w3c WebTransport specification](https://www.w3.org/TR/webtransport/), there are two ways for a browser to validate the certificate used on a WebTransport connection. 1. by verifying the chain of trust of the certificate. This means that the certificate has to be signed by a CA (Certificate Authority) that the browser trusts. This is how browsers verify certificates when establishing a regular HTTPS connection. 2. by verifying that the cryptographic hash of the certificate matches a specific value, using the [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes) option. From 0a9a7bbe044ed7a5a6d4666f021af034f1cf2c9b Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 12 Oct 2022 21:15:12 +0200 Subject: [PATCH 25/25] clarify that servers with a CA-signed certificate don't use /certhash --- webtransport/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/webtransport/README.md b/webtransport/README.md index 0010eca19..bbff42d3e 100644 --- a/webtransport/README.md +++ b/webtransport/README.md @@ -2,7 +2,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|--------------------------|--------|-----------------| -| 1A | Candidate Recommendation | Active | r0, 2022-09-28 | +| 1A | Candidate Recommendation | Active | r0, 2022-10-12 | Authors: [@marten-seemann] @@ -27,7 +27,7 @@ According to the [w3c WebTransport specification](https://www.w3.org/TR/webtrans 1. by verifying the chain of trust of the certificate. This means that the certificate has to be signed by a CA (Certificate Authority) that the browser trusts. This is how browsers verify certificates when establishing a regular HTTPS connection. 2. by verifying that the cryptographic hash of the certificate matches a specific value, using the [`serverCertificateHashes`](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes) option. -libp2p nodes that possess a CA-signed TLS certificate MAY use that certificate on WebTransport connections. +libp2p nodes that possess a CA-signed TLS certificate MAY use that certificate on WebTransport connections. These nodes SHOULD NOT add a `/certhash` component (see [Addressing](#addressing)) to addresses they advertise, since this will cause clients to verify the certificate by the hash (instead of verifying the certificate chain). The rest of this section applies to nodes that wish to use self-signed certificates and make use of the verification by certificate hash. @@ -38,10 +38,11 @@ Once the first certificate has expired, the node starts using the already genera ## Addressing -WebTransport multiaddresses are composed of a QUIC multiaddress, followed by `/webtransport` and a list of multihashes of the certificates that the server uses. +WebTransport multiaddresses are composed of a QUIC multiaddress, followed by `/webtransport` and a list of multihashes of the certificates that the server uses (if not using a CA-signed certificate). Examples: -* `/ip4/1.2.3.4/udp/443/quic/webtransport/certhash/` -* `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/certhash//certhash//certhash/` +* `/ip4/1.2.3.4/udp/443/quic/webtransport` (when using a CA-signed certificates) +* `/ip4/1.2.3.4/udp/1234/quic/webtransport/certhash/` (when using single self-signed certificates) +* `/ip6/fe80::1ff:fe23:4567:890a/udp/1234/quic/webtransport/certhash//certhash//certhash/` (when using single self-signed certificates) ## WebTransport HTTP endpoint