From dbde5fdecc0be08f03901bf2c9115a5654529425 Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Thu, 8 Sep 2022 12:56:40 -0700 Subject: [PATCH 01/50] Muxer selection in security handshake spec --- connections/muxer-sel-in-sec-handshake.md | 166 ++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 connections/muxer-sel-in-sec-handshake.md diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md new file mode 100644 index 000000000..8d74693cb --- /dev/null +++ b/connections/muxer-sel-in-sec-handshake.md @@ -0,0 +1,166 @@ +# Muxer selection in security handshake + + +| Lifecycle Stage | Maturity | Status | Latest Revision | +|-----------------|---------------|--------|-----------------| +| 1A | Working Draft | Active | r1, 2022-09-07 | + +Authors: [@julian88110] + +Interest Group: [@marten-seemann], [@marcopolo], [@mxinden] + +[@marten-seemann]: https://github.com/marten-seemann +[@marcopolo]: https://github.com/marcopolo +[@mxinden]: https://github.com/mxinden +[@julian88110]: https://github.com/julian88110 + +See the [lifecycle document][lifecycle-spec] for context about maturity level +and spec status. + +[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md + +## Overview + +This document discribes an imporvement on the connection upgrade process. The +goal of the improvement is to reduce the number of RTTs that takes to select the +muxer of a connection. The solution relies on the ability of the security +protocol's handshake process to negotiate higher level protocols, which enables +the muxer selection to be carried out along with security protocol handshake. +The proposed solution saves the RTT of multistream selection for muxers. + +For more context and the status of this work, please refer to [#426] + + +## The design + +### Current connection upgrade + +The current connection upgrade process is described in detail in [connections] +As shown in this [sequence-chart], after a network connection is established, +the following will happen to upgrade the conntection to a capable connection. + +1. The multistream-selection protocol is run over the connection to select the +security protocol to be used. +2. The selected security protocol performs handshaking and establishs a secure +tunnel +3. The multistream-selection protocol then will run again for muxer selection. +4. Connection then is upgraded to a capable connection by the selected muxer. + + +## Improved muxer selection + +The security protocol's ability of supporting higher level abstract protocol +negotiation (for example, TLS's support of NextProtos, and Noise's support of +Early Data) makes it possible to collapse the step 2 and step 3 in the +previous section into one step. Muxer selection can be performed as part of +the security protocol handshake, thus there is no need to perform another +mutistream-selection negotiation for muxer selection. + +In order to achieve the above stated goal, each candidate muxer will be +represented by a protocol name/code, and the candidate muxers are supplied to +the security protocol's handshake process as a list of protocol names. + +If the client and server agree upon the common muxer to be used, then the +result of the muxer selection is a muxer code represented by the selected +protocol name. If no agreement is reached upon by the client and server +then an empty muxer code is returned and the connection upgrade process +MUST fall back to the multistream-selection protocol to negotiate the muxer. + + +### Muxer selection over TLS + +When the security protocol selected by the upgrader is TLS, the [ALPN] +extesion of TLS handshake is used to select the muxer. + + With ALPN, the client sends the list of supported application + protocols as part of the TLS ClientHello message. The server chooses + a protocol and sends the selected protocol as part of the TLS + ServerHello message. The application protocol negotiation can thus + be accomplished within the TLS handshake, without adding network + round-trips, and allows the server to associate a different + certificate with each application protocol, if desired. + +For the purpose of muxer selection, the types of muxers are coded as protocol +names in the form of a list of strings, and inserted in the ALPN "NextProtos" +field. An example list as following: + + ["yamux/1.0.0", "mplux", "libp2p"] + +The NextProtos list is ordered by preference, with the most prefered muxer at +the beginning. The "libp2p" protocol code MUST always be the last item in the +ALPN NextProtos list. + +The server chooses the supported protocol by going through its prefered +protocol list and searchs if the protocol is supported by the client too. if no +mutually supported protcol is found the TLS handshake will fail. + +If the selected NextProto is "libp2p" then the muxer selection process returns +an empty result, and the multistream-selection protocol MUST be run to negotiate +the muxer. + +(TBD: in some cases early abortion is desireable) + + +## Muxer selection over Noise + +The libp2p Noise implementation allows the Noise handshake process to carry +early data. [Noise-Early-Data] is carried in the second and third message of +the handshake pattern: + + XX: + -> e + <- e, ee, s, es + -> s, se + +At the end of the handshake pattern, both the client and server have received +the peer's early data. The Noise protocol does not perform the protocol +selection as TLS does, rather it just delivers the early data to handshaking +peers. + +The muxer selection logic runs out of the Noise handshake process, relying on +the early data exchanged during the handshake. The early data is delivered in +the form of a byte string. The supported muxers are passed in space separated +string codes. An example early data string: + + "yamux/1.0.0 mplux" + +The byte string is ordered by preference, with the most prefered muxer at the +beginning. + +After the Noise handshake, the client and server run the muxer selection +process with the same logic. Each side will go through the server's early +data from most prefered to lest prefered muxer, and if the muxer is in the +client's early data list, that muxer is selected. The process guarantees that +both the client and server reaches at the same conclusion of muxer slection. + +If the muxer selection process does not find any mutually supported muxer, for +example, in the case that one early data string is empty, then an empty muxer +selection result is returned, and multistream-selection MUST be performed. + +(TBD: in some cases early abortion is desireable) + +## Cross version support + +The improved muxer selection approach MUST be inter-operable with pervious +libp2p versions. +In the current implementation of libp2p, the "NextProtos" field is populated with +a key "libp2p" so that the client and server alwways find that to be the mutal +protocol. + +## Security + +## Protocol coupling + +[#426]: https://github.com/libp2p/specs/issues/426 +[connections]: https://github.com/libp2p/specs/tree/master/connections +[sequnce-chart]: https://github.com/libp2p/specs/tree/master/connections#upgrading-connections +[ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 +[Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload + + + + + + + + From a8804ddae3df6ccdefaa3061f68e63684cd911a5 Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Fri, 9 Sep 2022 08:31:04 -0700 Subject: [PATCH 02/50] Add cross version and security sections --- connections/muxer-sel-in-sec-handshake.md | 32 ++++++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 8d74693cb..63ea1a493 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -142,13 +142,37 @@ selection result is returned, and multistream-selection MUST be performed. ## Cross version support The improved muxer selection approach MUST be inter-operable with pervious -libp2p versions. -In the current implementation of libp2p, the "NextProtos" field is populated with -a key "libp2p" so that the client and server alwways find that to be the mutal -protocol. +libp2p versions which do not support this improved approach. + +### TLS case + +In the current version of libp2p, the "NextProtos" field is populated with a +key "libp2p". By appending the key of "libp2p" to the end of the supported +muxer list, the TLS handshaking process is not broken when peers run different +versions of libp2p, because the minimum overlap of the peer's NextProtos sets +is always satisfied. When one peer runs the old version and the other peer runs +the version that supports this feature, the negotiated protocol is "libp2p". + +In the case "libp2p" is the result of TLS ALPN, an empty result MUST be +returned to the upgrade process to indicate that no muxer was selected. And the +upgrade process MUST fall back to the multistream-selection protocol to +to negotiate the muxer to be selected. + +### Noise case + +The existing version of libp2p Noise handshake carries empty early data. When a +version that supports this feature talks to an older version which does not +support this feature, the muxer selection process on the new version runs +against an empty string and will return empty muxer selection result. + +In the case an empty muxer selection result is returned, the upgrade process +MUST fall back to the multistream-selection protocol to select the muxer. ## Security +The muxer list carried in TLS NextProtos field is part of the ClientHello +message which is not encrypted. This feature will expose the supported muxers +in plain text, but this is not an weakening of securiy posture. ## Protocol coupling [#426]: https://github.com/libp2p/specs/issues/426 From ad1bae7ba3e9218ea524820f07f81e73075a8b9c Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Fri, 9 Sep 2022 11:45:56 -0700 Subject: [PATCH 03/50] Add security and more sections --- connections/muxer-sel-in-sec-handshake.md | 46 +++++++++++++++++++---- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 63ea1a493..765f00dc9 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -19,6 +19,22 @@ and spec status. [lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md +## Table of Contents + +- [Muxer selection in security handshake](#Muxer-selection-in-security-handshake) + - [Table of Contents](#table-of-contents) + - [Overview](#overview) + - [Design])(#Design) + - [Current connection upgrade process](#current-connection-upgrade-process) + - [Improved muxer selection](#improved-muxer-selection) + - [Muxer selection over TLS](#muxer-selection-over-tls) + - [Muxer selection over Noise](#muxer-selection-over-noise) + - [Cross version support](#cross-version-support) + - [TLS case](#tls-case) + - [Noise case](#noise-case) + - [Security](#security) + - [Protocol coupling](#protocol-coupling) + ## Overview This document discribes an imporvement on the connection upgrade process. The @@ -31,11 +47,11 @@ The proposed solution saves the RTT of multistream selection for muxers. For more context and the status of this work, please refer to [#426] -## The design +## Design -### Current connection upgrade +### Current connection upgrade process -The current connection upgrade process is described in detail in [connections] +The current connection upgrade process is described in detail in [connections]. As shown in this [sequence-chart], after a network connection is established, the following will happen to upgrade the conntection to a capable connection. @@ -101,7 +117,7 @@ the muxer. (TBD: in some cases early abortion is desireable) -## Muxer selection over Noise +### Muxer selection over Noise The libp2p Noise implementation allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the second and third message of @@ -141,7 +157,7 @@ selection result is returned, and multistream-selection MUST be performed. ## Cross version support -The improved muxer selection approach MUST be inter-operable with pervious +The improved muxer selection approach MUST be interoperable with pervious libp2p versions which do not support this improved approach. ### TLS case @@ -172,15 +188,29 @@ MUST fall back to the multistream-selection protocol to select the muxer. The muxer list carried in TLS NextProtos field is part of the ClientHello message which is not encrypted. This feature will expose the supported muxers -in plain text, but this is not an weakening of securiy posture. +in plain text, but this is not a weakening of securiy posture. In the fuure +when [ECH] is ready the muxer info can be protected too. + +The early data in Noise handshake is encrypted so that the muxer info carried +over is protected. These is no security weakening in this case either. + + ## Protocol coupling +This feature aggregates the multistream-selecion function and security +handshake function. From function separation point of view, it introduces +coupling between different functions. But the argument is that in the case of +libp2p, the muxer and security are always needed at the same time, and it is a +small price to pay to gain efficiency by ruducing one RTT. + + + [#426]: https://github.com/libp2p/specs/issues/426 [connections]: https://github.com/libp2p/specs/tree/master/connections -[sequnce-chart]: https://github.com/libp2p/specs/tree/master/connections#upgrading-connections +[sequence-chart]: https://github.com/libp2p/specs/tree/master/connections#upgrading-connections [ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 [Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload - +[ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ From 0d35e15b1eb458319563f3a1e36ef0259d985442 Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Mon, 12 Sep 2022 14:52:20 -0700 Subject: [PATCH 04/50] Address review feedback points, add protobuf. --- connections/muxer-sel-in-sec-handshake.md | 70 ++++++++++++++++------- 1 file changed, 49 insertions(+), 21 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 765f00dc9..8b5cea21e 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -24,11 +24,12 @@ and spec status. - [Muxer selection in security handshake](#Muxer-selection-in-security-handshake) - [Table of Contents](#table-of-contents) - [Overview](#overview) - - [Design])(#Design) + - [Design])(#design) - [Current connection upgrade process](#current-connection-upgrade-process) - [Improved muxer selection](#improved-muxer-selection) - [Muxer selection over TLS](#muxer-selection-over-tls) - [Muxer selection over Noise](#muxer-selection-over-noise) + - [Early data specification](#early-data-specification) - [Cross version support](#cross-version-support) - [TLS case](#tls-case) - [Noise case](#noise-case) @@ -66,11 +67,11 @@ tunnel ## Improved muxer selection The security protocol's ability of supporting higher level abstract protocol -negotiation (for example, TLS's support of NextProtos, and Noise's support of -Early Data) makes it possible to collapse the step 2 and step 3 in the -previous section into one step. Muxer selection can be performed as part of -the security protocol handshake, thus there is no need to perform another -mutistream-selection negotiation for muxer selection. +negotiation (for example, TLS's support of ALPN, and Noise's support of Early +Data) makes it possible to collapse the step 2 and step 3 in the previous +section into one step. Muxer selection can be performed as part of the security +protocol handshake, thus there is no need to perform another mutistream +-selection negotiation for muxer selection. In order to achieve the above stated goal, each candidate muxer will be represented by a protocol name/code, and the candidate muxers are supplied to @@ -114,19 +115,17 @@ If the selected NextProto is "libp2p" then the muxer selection process returns an empty result, and the multistream-selection protocol MUST be run to negotiate the muxer. -(TBD: in some cases early abortion is desireable) - ### Muxer selection over Noise The libp2p Noise implementation allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the second and third message of -the handshake pattern: +the handshake pattern as illustrated in the following message sequence chart. XX: -> e - <- e, ee, s, es - -> s, se + <- e, ee, s, es, _early-data_ + -> s, se, _early-data_ At the end of the handshake pattern, both the client and server have received the peer's early data. The Noise protocol does not perform the protocol @@ -135,13 +134,12 @@ peers. The muxer selection logic runs out of the Noise handshake process, relying on the early data exchanged during the handshake. The early data is delivered in -the form of a byte string. The supported muxers are passed in space separated -string codes. An example early data string: - - "yamux/1.0.0 mplux" - -The byte string is ordered by preference, with the most prefered muxer at the -beginning. +the form of a byte string in the second and third message of the XX handshake +pattern. + +The early data for this purpose is specified in the protobuf in the +[Early-data-specification] section. The muxers are ordered by preference, with +the most prefered muxer at the beginning. After the Noise handshake, the client and server run the muxer selection process with the same logic. Each side will go through the server's early @@ -153,7 +151,34 @@ If the muxer selection process does not find any mutually supported muxer, for example, in the case that one early data string is empty, then an empty muxer selection result is returned, and multistream-selection MUST be performed. -(TBD: in some cases early abortion is desireable) +#### Early data specification + +The early data message is encoded in the "protobuf2" syntax as shown in the +following. The protobuf definition is an extension to [handshake-payload]. The +existing byte array early data (the "data" field) will be replaced by a +structured EarlyData schema. + + (TBD: verify backward compatiblity) + +```protobuf +syntax = "proto2"; + +message EarlyData { + message Muxer { + oneof Muxer { + string name = 1; + } + } + repeated Muxer muxers = 2; +} + +message NoiseHandshakePayload { + bytes identity_key = 1; + bytes identity_sig = 2; + EarlyData early_data = 3; +} +``` + ## Cross version support @@ -191,8 +216,10 @@ message which is not encrypted. This feature will expose the supported muxers in plain text, but this is not a weakening of securiy posture. In the fuure when [ECH] is ready the muxer info can be protected too. -The early data in Noise handshake is encrypted so that the muxer info carried -over is protected. These is no security weakening in this case either. +The early data in Noise handshake is only sent afer the peers establish a +shared key, in the second and third handshake messages in the XX pattern. So +the early data is encrypted and the muxer info carried over is protected. +These is no security weakening in this case either. ## Protocol coupling @@ -211,6 +238,7 @@ small price to pay to gain efficiency by ruducing one RTT. [ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 [Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload [ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ +[handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload From ec2e959a28beae5c568af21c7151015928b8c489 Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Tue, 13 Sep 2022 13:25:31 -0700 Subject: [PATCH 05/50] Address some more review points. Update Noise handshake section, Revise muxer string in examples. --- connections/muxer-sel-in-sec-handshake.md | 53 ++++++++++++++--------- 1 file changed, 33 insertions(+), 20 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 8b5cea21e..50843ecb6 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -101,7 +101,7 @@ For the purpose of muxer selection, the types of muxers are coded as protocol names in the form of a list of strings, and inserted in the ALPN "NextProtos" field. An example list as following: - ["yamux/1.0.0", "mplux", "libp2p"] + ["yamux/1.0.0", "/mplex/6.7.0", "libp2p"] The NextProtos list is ordered by preference, with the most prefered muxer at the beginning. The "libp2p" protocol code MUST always be the last item in the @@ -119,20 +119,35 @@ the muxer. ### Muxer selection over Noise The libp2p Noise implementation allows the Noise handshake process to carry -early data. [Noise-Early-Data] is carried in the second and third message of -the handshake pattern as illustrated in the following message sequence chart. +early data. [Noise-Early-Data] is carried in the first and second message of +the XX handshake pattern as illustrated in the following message sequence chart. +The first message carries early data in the form of a list of muxers supported +by the initiator, ordered by preference. The responder goes through the list in +the order of preference, and finds the first muxer that is mutually supported +by both the initator and the responder, and then populates the selected muxer +in the second message, sent by the responder. If no mutually supported muxer is +found, the early data in the second message is empty. + +Example: Noise handshake between peers that have a mutually supported muxer. + Initiator supports: ["yamux/1.0.0", "/mplex/6.7.0"] + Responder supports: ["yamux/1.0.0"] XX: - -> e - <- e, ee, s, es, _early-data_ - -> s, se, _early-data_ + -> e ["yamux/1.0.0", "/mplex/6.7.0"] + <- e, ee, s, es, ["yamux/1.0.0"] + -> s, se, -At the end of the handshake pattern, both the client and server have received -the peer's early data. The Noise protocol does not perform the protocol -selection as TLS does, rather it just delivers the early data to handshaking -peers. +Example: Noise handshake between peers that don't have mutually supported +muxers. + Initiator supports: ["/mplex/6.7.0"] + Responder supports: ["yamux/1.0.0"] -The muxer selection logic runs out of the Noise handshake process, relying on + XX: + -> e ["/mplex/6.7.0"] + <- e, ee, s, es, [] + -> s, se, + +The muxer selection logic runs as a plugin of the Noise handshake logic, relying the early data exchanged during the handshake. The early data is delivered in the form of a byte string in the second and third message of the XX handshake pattern. @@ -156,26 +171,24 @@ selection result is returned, and multistream-selection MUST be performed. The early data message is encoded in the "protobuf2" syntax as shown in the following. The protobuf definition is an extension to [handshake-payload]. The existing byte array early data (the "data" field) will be replaced by a -structured EarlyData schema. +structured NoiseExtension schema. The supported muxers and selected muxer are +populated in the "stream_muxers" field. (TBD: verify backward compatiblity) ```protobuf syntax = "proto2"; -message EarlyData { - message Muxer { - oneof Muxer { - string name = 1; - } - } - repeated Muxer muxers = 2; +message NoiseExtension { + repeated bytes webtransport_certhashes = 1; + optional bytes webrtc_fingerprint = 2; + repeated string stream_muxers = 3; } message NoiseHandshakePayload { bytes identity_key = 1; bytes identity_sig = 2; - EarlyData early_data = 3; + NoiseExtension noise_extension = 3; } ``` From 00423843b4df19812757b0ebf1609f388c827e7e Mon Sep 17 00:00:00 2001 From: Jinqiang Yang Date: Tue, 13 Sep 2022 14:14:37 -0700 Subject: [PATCH 06/50] Correct some typos --- connections/muxer-sel-in-sec-handshake.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 50843ecb6..4f7197aaf 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -24,7 +24,7 @@ and spec status. - [Muxer selection in security handshake](#Muxer-selection-in-security-handshake) - [Table of Contents](#table-of-contents) - [Overview](#overview) - - [Design])(#design) + - [Design](#design) - [Current connection upgrade process](#current-connection-upgrade-process) - [Improved muxer selection](#improved-muxer-selection) - [Muxer selection over TLS](#muxer-selection-over-tls) @@ -241,7 +241,7 @@ This feature aggregates the multistream-selecion function and security handshake function. From function separation point of view, it introduces coupling between different functions. But the argument is that in the case of libp2p, the muxer and security are always needed at the same time, and it is a -small price to pay to gain efficiency by ruducing one RTT. +small price to pay to gain efficiency by reducing one RTT. From dcac239cd78fa7783ac1f2f9b5464d903addf1b5 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Thu, 15 Sep 2022 15:37:34 -0700 Subject: [PATCH 07/50] Address feedback points and update noise section --- connections/muxer-sel-in-sec-handshake.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 4f7197aaf..f46e489ed 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -122,11 +122,14 @@ The libp2p Noise implementation allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the first and second message of the XX handshake pattern as illustrated in the following message sequence chart. The first message carries early data in the form of a list of muxers supported -by the initiator, ordered by preference. The responder goes through the list in -the order of preference, and finds the first muxer that is mutually supported -by both the initator and the responder, and then populates the selected muxer -in the second message, sent by the responder. If no mutually supported muxer is -found, the early data in the second message is empty. +by the initiator, ordered by preference. The responder sends its supported +muxer list in the second message to the initiator. After the Noise handshake +process is fully done, the initiator and responder will both process the +received eraly data and select the muxer to be used, they both iterate through +the initiator's prefered muxer list in order, and if any muxer is also +supported by the responder, that muxer is selected. If no mutually supported +muxer is found, the muxer selection process MUST fall back to multistream +-selection protocol. Example: Noise handshake between peers that have a mutually supported muxer. Initiator supports: ["yamux/1.0.0", "/mplex/6.7.0"] @@ -137,6 +140,9 @@ Example: Noise handshake between peers that have a mutually supported muxer. <- e, ee, s, es, ["yamux/1.0.0"] -> s, se, + After handshake is done, both parties can arrive on the same conclusion + and select "yamux/1.0.0" as the muxer to use. + Example: Noise handshake between peers that don't have mutually supported muxers. Initiator supports: ["/mplex/6.7.0"] @@ -144,8 +150,11 @@ muxers. XX: -> e ["/mplex/6.7.0"] - <- e, ee, s, es, [] + <- e, ee, s, es, ["yamux/1.0.0"] -> s, se, + + After handshaking is done, early data processing will find no mutually + supported muxer, and falls back to multistream-selection protocol. The muxer selection logic runs as a plugin of the Noise handshake logic, relying the early data exchanged during the handshake. The early data is delivered in From 245361c4a7df940b7d8b558b641cf8ef7a9f00f5 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Thu, 15 Sep 2022 15:39:24 -0700 Subject: [PATCH 08/50] update Noise extention protobuf --- connections/muxer-sel-in-sec-handshake.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index f46e489ed..1e47da73d 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -189,15 +189,13 @@ populated in the "stream_muxers" field. syntax = "proto2"; message NoiseExtension { - repeated bytes webtransport_certhashes = 1; - optional bytes webrtc_fingerprint = 2; repeated string stream_muxers = 3; } message NoiseHandshakePayload { bytes identity_key = 1; bytes identity_sig = 2; - NoiseExtension noise_extension = 3; + NoiseExtension noise_extension = 4; } ``` From a5b3ef01fe20715fb25d8cf571aceb8a44a35a4c Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Thu, 15 Sep 2022 15:43:41 -0700 Subject: [PATCH 09/50] Remove TBD item --- connections/muxer-sel-in-sec-handshake.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 1e47da73d..197dc499a 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -183,8 +183,6 @@ existing byte array early data (the "data" field) will be replaced by a structured NoiseExtension schema. The supported muxers and selected muxer are populated in the "stream_muxers" field. - (TBD: verify backward compatiblity) - ```protobuf syntax = "proto2"; From 349ac767185cfed3a06123d13350151dca777e8a Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Thu, 15 Sep 2022 16:03:47 -0700 Subject: [PATCH 10/50] Remove some redandant info --- connections/muxer-sel-in-sec-handshake.md | 25 ++++++----------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 197dc499a..eb7b45316 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -156,24 +156,9 @@ muxers. After handshaking is done, early data processing will find no mutually supported muxer, and falls back to multistream-selection protocol. -The muxer selection logic runs as a plugin of the Noise handshake logic, relying -the early data exchanged during the handshake. The early data is delivered in -the form of a byte string in the second and third message of the XX handshake -pattern. - -The early data for this purpose is specified in the protobuf in the -[Early-data-specification] section. The muxers are ordered by preference, with -the most prefered muxer at the beginning. - -After the Noise handshake, the client and server run the muxer selection -process with the same logic. Each side will go through the server's early -data from most prefered to lest prefered muxer, and if the muxer is in the -client's early data list, that muxer is selected. The process guarantees that -both the client and server reaches at the same conclusion of muxer slection. - -If the muxer selection process does not find any mutually supported muxer, for -example, in the case that one early data string is empty, then an empty muxer -selection result is returned, and multistream-selection MUST be performed. +The muxer selection logic is run outside of the Noise handshake process. The +format of he early data for this purpose is specified in the protobuf in the +[Early-data-specification] section. #### Early data specification @@ -183,6 +168,9 @@ existing byte array early data (the "data" field) will be replaced by a structured NoiseExtension schema. The supported muxers and selected muxer are populated in the "stream_muxers" field. +The muxers are ordered by preference, with the most prefered muxer at the +beginning. + ```protobuf syntax = "proto2"; @@ -197,7 +185,6 @@ message NoiseHandshakePayload { } ``` - ## Cross version support The improved muxer selection approach MUST be interoperable with pervious From d6eb581899bf081df49c3b9f087bffc73955d65e Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 20 Sep 2022 11:22:27 -0700 Subject: [PATCH 11/50] add alternative options considered --- connections/muxer-sel-in-sec-handshake.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index eb7b45316..943417038 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -35,6 +35,7 @@ and spec status. - [Noise case](#noise-case) - [Security](#security) - [Protocol coupling](#protocol-coupling) + - [Alternative options considered](#alternative-options-considered) ## Overview @@ -236,6 +237,13 @@ libp2p, the muxer and security are always needed at the same time, and it is a small price to pay to gain efficiency by reducing one RTT. +## Alternative options considered + +Instead of ALPN for muxer selection to reduce RTT, other options such as TLS +extension and X.509 extension are considered. The pros and cons are explored +and the discussion details can be found at [#454]. + + [#426]: https://github.com/libp2p/specs/issues/426 [connections]: https://github.com/libp2p/specs/tree/master/connections @@ -244,6 +252,7 @@ small price to pay to gain efficiency by reducing one RTT. [Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload [ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ [handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload +[#454]: https://github.com/libp2p/specs/issues/454 From c7a1db0e798e27f58214995794fb27abd29dc95e Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Fri, 23 Sep 2022 13:47:54 -0700 Subject: [PATCH 12/50] Update noise registration with NoiseExtensions field for muxers. --- connections/muxer-sel-in-sec-handshake.md | 17 ++++++++++------- noise/README.md | 1 + 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 943417038..dececc570 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -166,8 +166,9 @@ format of he early data for this purpose is specified in the protobuf in the The early data message is encoded in the "protobuf2" syntax as shown in the following. The protobuf definition is an extension to [handshake-payload]. The existing byte array early data (the "data" field) will be replaced by a -structured NoiseExtension schema. The supported muxers and selected muxer are -populated in the "stream_muxers" field. +structured NoiseExtensions protobuf message. The supported muxers and selected +muxer are populated in the "stream_muxers" field. The details of the early +data message can be find in [Noise-handshake-payload] The muxers are ordered by preference, with the most prefered muxer at the beginning. @@ -175,14 +176,15 @@ beginning. ```protobuf syntax = "proto2"; -message NoiseExtension { - repeated string stream_muxers = 3; +message NoiseExtensions { + repeated bytes webtransport_certhashes = 1; + repeated string stream_muxers = 2; } message NoiseHandshakePayload { - bytes identity_key = 1; - bytes identity_sig = 2; - NoiseExtension noise_extension = 4; + optional bytes identity_key = 1; + optional bytes identity_sig = 2; + optional NoiseExtensions extensions = 4; } ``` @@ -253,6 +255,7 @@ and the discussion details can be found at [#454]. [ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ [handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload [#454]: https://github.com/libp2p/specs/issues/454 +[Noise-handshake-payload]: https://github.com/libp2p/specs/blob/b0818fa956f9940a7cdee18198e0daf1645d8276/noise/README.md#libp2p-data-in-handshake-messages diff --git a/noise/README.md b/noise/README.md index 7648b06d1..3cb09d9ba 100644 --- a/noise/README.md +++ b/noise/README.md @@ -220,6 +220,7 @@ syntax = "proto2"; message NoiseExtensions { repeated bytes webtransport_certhashes = 1; + repeated string stream_muxers = 2; } message NoiseHandshakePayload { From 811fc0545221bd1525df650cde631aaf4ab43e71 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 27 Sep 2022 11:23:43 -0700 Subject: [PATCH 13/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Max Inden --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index dececc570..98ef3dad4 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -106,7 +106,7 @@ field. An example list as following: The NextProtos list is ordered by preference, with the most prefered muxer at the beginning. The "libp2p" protocol code MUST always be the last item in the -ALPN NextProtos list. +ALPN NextProtos list. See [#tls-case] for details on the special "libp2p" protocol code. The server chooses the supported protocol by going through its prefered protocol list and searchs if the protocol is supported by the client too. if no From 239dfca3069b9286e125b2f55fe3cf6ba3b23405 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 27 Sep 2022 11:24:26 -0700 Subject: [PATCH 14/50] Revise noise handshake section to reflect early data carrier msg change. --- connections/muxer-sel-in-sec-handshake.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index dececc570..5be87259e 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -120,11 +120,11 @@ the muxer. ### Muxer selection over Noise The libp2p Noise implementation allows the Noise handshake process to carry -early data. [Noise-Early-Data] is carried in the first and second message of +early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. -The first message carries early data in the form of a list of muxers supported -by the initiator, ordered by preference. The responder sends its supported -muxer list in the second message to the initiator. After the Noise handshake +The second message carries early data in the form of a list of muxers supported +by the responder, ordered by preference. The initiator sends its supported +muxer list in the third message to the responder. After the Noise handshake process is fully done, the initiator and responder will both process the received eraly data and select the muxer to be used, they both iterate through the initiator's prefered muxer list in order, and if any muxer is also @@ -137,9 +137,9 @@ Example: Noise handshake between peers that have a mutually supported muxer. Responder supports: ["yamux/1.0.0"] XX: - -> e ["yamux/1.0.0", "/mplex/6.7.0"] - <- e, ee, s, es, ["yamux/1.0.0"] - -> s, se, + -> e + <- e, ee, s, es, ["yamux/1.0.0", "/mplex/6.7.0"] + -> s, se, ["yamux/1.0.0"] After handshake is done, both parties can arrive on the same conclusion and select "yamux/1.0.0" as the muxer to use. @@ -150,9 +150,9 @@ muxers. Responder supports: ["yamux/1.0.0"] XX: - -> e ["/mplex/6.7.0"] - <- e, ee, s, es, ["yamux/1.0.0"] - -> s, se, + -> e + <- e, ee, s, es, ["/mplex/6.7.0"] + -> s, se, ["yamux/1.0.0"] After handshaking is done, early data processing will find no mutually supported muxer, and falls back to multistream-selection protocol. From 1c716e2b41fa59d46c0320fd525e4017406533d6 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 27 Sep 2022 12:00:37 -0700 Subject: [PATCH 15/50] Correct sequence example in noise handshake --- connections/muxer-sel-in-sec-handshake.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 08f4d151a..6b8ea2caf 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -133,8 +133,8 @@ muxer is found, the muxer selection process MUST fall back to multistream -selection protocol. Example: Noise handshake between peers that have a mutually supported muxer. - Initiator supports: ["yamux/1.0.0", "/mplex/6.7.0"] - Responder supports: ["yamux/1.0.0"] + Responder supports: ["yamux/1.0.0", "/mplex/6.7.0"] + Initiator supports: ["yamux/1.0.0"] XX: -> e @@ -146,8 +146,8 @@ Example: Noise handshake between peers that have a mutually supported muxer. Example: Noise handshake between peers that don't have mutually supported muxers. - Initiator supports: ["/mplex/6.7.0"] - Responder supports: ["yamux/1.0.0"] + Responder supports: ["/mplex/6.7.0"] + Initiator supports: ["yamux/1.0.0"] XX: -> e From 24d021d0883e6240da87b654e6f71f8a89a5b591 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 27 Sep 2022 12:13:01 -0700 Subject: [PATCH 16/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 6b8ea2caf..3f55561cf 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -102,7 +102,7 @@ For the purpose of muxer selection, the types of muxers are coded as protocol names in the form of a list of strings, and inserted in the ALPN "NextProtos" field. An example list as following: - ["yamux/1.0.0", "/mplex/6.7.0", "libp2p"] + ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] The NextProtos list is ordered by preference, with the most prefered muxer at the beginning. The "libp2p" protocol code MUST always be the last item in the From 5c28fc1abc99fbdaf95a850020db3835f2da19d3 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 27 Sep 2022 12:54:21 -0700 Subject: [PATCH 17/50] replace nextproto with ALPN extension --- connections/muxer-sel-in-sec-handshake.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 6b8ea2caf..01375fa24 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -99,22 +99,22 @@ extesion of TLS handshake is used to select the muxer. certificate with each application protocol, if desired. For the purpose of muxer selection, the types of muxers are coded as protocol -names in the form of a list of strings, and inserted in the ALPN "NextProtos" +names in the form of a list of strings, and inserted in the ALPN extension field. An example list as following: ["yamux/1.0.0", "/mplex/6.7.0", "libp2p"] -The NextProtos list is ordered by preference, with the most prefered muxer at +The muxer list is ordered by preference, with the most prefered muxer at the beginning. The "libp2p" protocol code MUST always be the last item in the -ALPN NextProtos list. See [#tls-case] for details on the special "libp2p" protocol code. +muxer list . See [#tls-case] for details on the special "libp2p" protocol code. The server chooses the supported protocol by going through its prefered protocol list and searchs if the protocol is supported by the client too. if no mutually supported protcol is found the TLS handshake will fail. -If the selected NextProto is "libp2p" then the muxer selection process returns -an empty result, and the multistream-selection protocol MUST be run to negotiate -the muxer. +If the selected item from the muxer list is "libp2p" then the muxer selection +process returns an empty result, and the multistream-selection protocol MUST be +run to negotiate the muxer. ### Muxer selection over Noise @@ -195,12 +195,13 @@ libp2p versions which do not support this improved approach. ### TLS case -In the current version of libp2p, the "NextProtos" field is populated with a +In the current version of libp2p, the ALPN extension field is populated with a key "libp2p". By appending the key of "libp2p" to the end of the supported muxer list, the TLS handshaking process is not broken when peers run different -versions of libp2p, because the minimum overlap of the peer's NextProtos sets -is always satisfied. When one peer runs the old version and the other peer runs -the version that supports this feature, the negotiated protocol is "libp2p". +versions of libp2p, because the minimum overlap of the peer's supported muxer +sets is always satisfied. When one peer runs the old version and the other peer +runs the version that supports this feature, the negotiated protocol is +"libp2p". In the case "libp2p" is the result of TLS ALPN, an empty result MUST be returned to the upgrade process to indicate that no muxer was selected. And the @@ -219,7 +220,7 @@ MUST fall back to the multistream-selection protocol to select the muxer. ## Security -The muxer list carried in TLS NextProtos field is part of the ClientHello +The muxer list carried in TLS ALPN extension field is part of the ClientHello message which is not encrypted. This feature will expose the supported muxers in plain text, but this is not a weakening of securiy posture. In the fuure when [ECH] is ready the muxer info can be protected too. From c6b8ed24f14417ab9df3a8346054c4c9209ceb39 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 10:59:24 -0700 Subject: [PATCH 18/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 0bb2793cc..97349d1d3 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -44,7 +44,7 @@ goal of the improvement is to reduce the number of RTTs that takes to select the muxer of a connection. The solution relies on the ability of the security protocol's handshake process to negotiate higher level protocols, which enables the muxer selection to be carried out along with security protocol handshake. -The proposed solution saves the RTT of multistream selection for muxers. +With this improvement, negotiation of the stream multiplexer doesn't consume any additional roundtrips. For more context and the status of this work, please refer to [#426] From 54379a95a7c68ff85cdd15e636d54aa3bf2daeb0 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 11:00:04 -0700 Subject: [PATCH 19/50] Update title --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 0bb2793cc..0fdd77f85 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -1,4 +1,4 @@ -# Muxer selection in security handshake +# Muxer negotiation in security handshake | Lifecycle Stage | Maturity | Status | Latest Revision | From cc2bbcb1b31afb07aff31d779f1e5f4bf9a867b1 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 11:00:49 -0700 Subject: [PATCH 20/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 1 - 1 file changed, 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 97349d1d3..5164ccf69 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -46,7 +46,6 @@ protocol's handshake process to negotiate higher level protocols, which enables the muxer selection to be carried out along with security protocol handshake. With this improvement, negotiation of the stream multiplexer doesn't consume any additional roundtrips. -For more context and the status of this work, please refer to [#426] ## Design From f81c6f482f6f2b0c83a1015e835504e677a5deed Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 11:26:28 -0700 Subject: [PATCH 21/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 5164ccf69..c47ef0c62 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -61,7 +61,7 @@ security protocol to be used. 2. The selected security protocol performs handshaking and establishs a secure tunnel 3. The multistream-selection protocol then will run again for muxer selection. -4. Connection then is upgraded to a capable connection by the selected muxer. +4. The selected muxer is then used on the secured connection. ## Improved muxer selection From 0b73a38b7a2684fba2db5910eaa1c18216b38a42 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 11:29:22 -0700 Subject: [PATCH 22/50] address some review points --- connections/muxer-sel-in-sec-handshake.md | 123 +++++++++++----------- 1 file changed, 63 insertions(+), 60 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index eabccae3b..b10ee981a 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -1,4 +1,4 @@ -# Muxer negotiation in security handshake +# Stream multiplexer negotiation in security handshake | Lifecycle Stage | Maturity | Status | Latest Revision | @@ -21,14 +21,14 @@ and spec status. ## Table of Contents -- [Muxer selection in security handshake](#Muxer-selection-in-security-handshake) +- [multiplexer selection in security handshake](#multiplexer-selection-in-security-handshake) - [Table of Contents](#table-of-contents) - [Overview](#overview) - [Design](#design) - [Current connection upgrade process](#current-connection-upgrade-process) - - [Improved muxer selection](#improved-muxer-selection) - - [Muxer selection over TLS](#muxer-selection-over-tls) - - [Muxer selection over Noise](#muxer-selection-over-noise) + - [Improved multiplexer selection](#improved-multiplexer-selection) + - [Multiplexer selection over TLS](#multiplexer-selection-over-tls) + - [Multiplexer selection over Noise](#multiplexer-selection-over-noise) - [Early data specification](#early-data-specification) - [Cross version support](#cross-version-support) - [TLS case](#tls-case) @@ -39,12 +39,14 @@ and spec status. ## Overview -This document discribes an imporvement on the connection upgrade process. The -goal of the improvement is to reduce the number of RTTs that takes to select the -muxer of a connection. The solution relies on the ability of the security +This document discribes an imporvement on the stream multiplexer negotiation +process. The goal of the improvement is to reduce the number of RTTs that takes +to negotiate the stream multiplexer for a transport that does not natively +support stream multiplexing. The solution relies on the ability of the security protocol's handshake process to negotiate higher level protocols, which enables -the muxer selection to be carried out along with security protocol handshake. -With this improvement, negotiation of the stream multiplexer doesn't consume any additional roundtrips. +the multiplexer negotiation to be carried out along with the security protocol +handshake. With this improvement, the negotiation of the stream multiplexer +doesn't consume any additional roundtrips. For more context and the status of this work, please refer to [#426] @@ -55,40 +57,41 @@ For more context and the status of this work, please refer to [#426] The current connection upgrade process is described in detail in [connections]. As shown in this [sequence-chart], after a network connection is established, -the following will happen to upgrade the conntection to a capable connection. +the following will happen to upgrade the conntection to a secured and stream- +multiplexed onnection. 1. The multistream-selection protocol is run over the connection to select the security protocol to be used. 2. The selected security protocol performs handshaking and establishs a secure tunnel -3. The multistream-selection protocol then will run again for muxer selection. -4. Connection then is upgraded to a capable connection by the selected muxer. +3. The multistream-selection protocol then will run again for multiplexer selection. +4. Connection then is upgraded to a capable connection by the selected multiplexer. -## Improved muxer selection +## Improved multiplexer selection The security protocol's ability of supporting higher level abstract protocol negotiation (for example, TLS's support of ALPN, and Noise's support of Early Data) makes it possible to collapse the step 2 and step 3 in the previous -section into one step. Muxer selection can be performed as part of the security +section into one step. multiplexer selection can be performed as part of the security protocol handshake, thus there is no need to perform another mutistream --selection negotiation for muxer selection. +-selection negotiation for multiplexer selection. -In order to achieve the above stated goal, each candidate muxer will be -represented by a protocol name/code, and the candidate muxers are supplied to +In order to achieve the above stated goal, each candidate multiplexer will be +represented by a protocol name/code, and the candidate multiplexers are supplied to the security protocol's handshake process as a list of protocol names. -If the client and server agree upon the common muxer to be used, then the -result of the muxer selection is a muxer code represented by the selected +If the client and server agree upon the common multiplexer to be used, then the +result of the multiplexer selection is a multiplexer code represented by the selected protocol name. If no agreement is reached upon by the client and server -then an empty muxer code is returned and the connection upgrade process -MUST fall back to the multistream-selection protocol to negotiate the muxer. +then an empty multiplexer code is returned and the connection upgrade process +MUST fall back to the multistream-selection protocol to negotiate the multiplexer. -### Muxer selection over TLS +### multiplexer selection over TLS When the security protocol selected by the upgrader is TLS, the [ALPN] -extesion of TLS handshake is used to select the muxer. +extesion of TLS handshake is used to select the multiplexer. With ALPN, the client sends the list of supported application protocols as part of the TLS ClientHello message. The server chooses @@ -98,41 +101,41 @@ extesion of TLS handshake is used to select the muxer. round-trips, and allows the server to associate a different certificate with each application protocol, if desired. -For the purpose of muxer selection, the types of muxers are coded as protocol +For the purpose of multiplexer selection, the types of multiplexers are coded as protocol names in the form of a list of strings, and inserted in the ALPN extension field. An example list as following: ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] -The muxer list is ordered by preference, with the most prefered muxer at +The multiplexer list is ordered by preference, with the most prefered multiplexer at the beginning. The "libp2p" protocol code MUST always be the last item in the -muxer list . See [#tls-case] for details on the special "libp2p" protocol code. +multiplexer list . See [#tls-case] for details on the special "libp2p" protocol code. The server chooses the supported protocol by going through its prefered protocol list and searchs if the protocol is supported by the client too. if no mutually supported protcol is found the TLS handshake will fail. -If the selected item from the muxer list is "libp2p" then the muxer selection +If the selected item from the multiplexer list is "libp2p" then the multiplexer selection process returns an empty result, and the multistream-selection protocol MUST be -run to negotiate the muxer. +run to negotiate the multiplexer. -### Muxer selection over Noise +### multiplexer selection over Noise The libp2p Noise implementation allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. -The second message carries early data in the form of a list of muxers supported +The second message carries early data in the form of a list of multiplexers supported by the responder, ordered by preference. The initiator sends its supported -muxer list in the third message to the responder. After the Noise handshake +multiplexer list in the third message to the responder. After the Noise handshake process is fully done, the initiator and responder will both process the -received eraly data and select the muxer to be used, they both iterate through -the initiator's prefered muxer list in order, and if any muxer is also -supported by the responder, that muxer is selected. If no mutually supported -muxer is found, the muxer selection process MUST fall back to multistream +received eraly data and select the multiplexer to be used, they both iterate through +the initiator's prefered multiplexer list in order, and if any multiplexer is also +supported by the responder, that multiplexer is selected. If no mutually supported +multiplexer is found, the multiplexer selection process MUST fall back to multistream -selection protocol. -Example: Noise handshake between peers that have a mutually supported muxer. +Example: Noise handshake between peers that have a mutually supported multiplexer. Responder supports: ["yamux/1.0.0", "/mplex/6.7.0"] Initiator supports: ["yamux/1.0.0"] @@ -142,10 +145,10 @@ Example: Noise handshake between peers that have a mutually supported muxer. -> s, se, ["yamux/1.0.0"] After handshake is done, both parties can arrive on the same conclusion - and select "yamux/1.0.0" as the muxer to use. + and select "yamux/1.0.0" as the multiplexer to use. Example: Noise handshake between peers that don't have mutually supported -muxers. +multiplexers. Responder supports: ["/mplex/6.7.0"] Initiator supports: ["yamux/1.0.0"] @@ -155,9 +158,9 @@ muxers. -> s, se, ["yamux/1.0.0"] After handshaking is done, early data processing will find no mutually - supported muxer, and falls back to multistream-selection protocol. + supported multiplexer, and falls back to multistream-selection protocol. -The muxer selection logic is run outside of the Noise handshake process. The +The multiplexer selection logic is run outside of the Noise handshake process. The format of he early data for this purpose is specified in the protobuf in the [Early-data-specification] section. @@ -166,11 +169,11 @@ format of he early data for this purpose is specified in the protobuf in the The early data message is encoded in the "protobuf2" syntax as shown in the following. The protobuf definition is an extension to [handshake-payload]. The existing byte array early data (the "data" field) will be replaced by a -structured NoiseExtensions protobuf message. The supported muxers and selected -muxer are populated in the "stream_muxers" field. The details of the early +structured NoiseExtensions protobuf message. The supported multiplexers and selected +multiplexer are populated in the "stream_multiplexers" field. The details of the early data message can be find in [Noise-handshake-payload] -The muxers are ordered by preference, with the most prefered muxer at the +The multiplexers are ordered by preference, with the most prefered multiplexer at the beginning. ```protobuf @@ -178,7 +181,7 @@ syntax = "proto2"; message NoiseExtensions { repeated bytes webtransport_certhashes = 1; - repeated string stream_muxers = 2; + repeated string stream_multiplexers = 2; } message NoiseHandshakePayload { @@ -190,44 +193,44 @@ message NoiseHandshakePayload { ## Cross version support -The improved muxer selection approach MUST be interoperable with pervious +The improved multiplexer selection approach MUST be interoperable with pervious libp2p versions which do not support this improved approach. ### TLS case In the current version of libp2p, the ALPN extension field is populated with a key "libp2p". By appending the key of "libp2p" to the end of the supported -muxer list, the TLS handshaking process is not broken when peers run different -versions of libp2p, because the minimum overlap of the peer's supported muxer +multiplexer list, the TLS handshaking process is not broken when peers run different +versions of libp2p, because the minimum overlap of the peer's supported multiplexer sets is always satisfied. When one peer runs the old version and the other peer runs the version that supports this feature, the negotiated protocol is "libp2p". In the case "libp2p" is the result of TLS ALPN, an empty result MUST be -returned to the upgrade process to indicate that no muxer was selected. And the +returned to the upgrade process to indicate that no multiplexer was selected. And the upgrade process MUST fall back to the multistream-selection protocol to -to negotiate the muxer to be selected. +to negotiate the multiplexer to be selected. ### Noise case The existing version of libp2p Noise handshake carries empty early data. When a version that supports this feature talks to an older version which does not -support this feature, the muxer selection process on the new version runs -against an empty string and will return empty muxer selection result. +support this feature, the multiplexer selection process on the new version runs +against an empty string and will return empty multiplexer selection result. -In the case an empty muxer selection result is returned, the upgrade process -MUST fall back to the multistream-selection protocol to select the muxer. +In the case an empty multiplexer selection result is returned, the upgrade process +MUST fall back to the multistream-selection protocol to select the multiplexer. ## Security -The muxer list carried in TLS ALPN extension field is part of the ClientHello -message which is not encrypted. This feature will expose the supported muxers +The multiplexer list carried in TLS ALPN extension field is part of the ClientHello +message which is not encrypted. This feature will expose the supported multiplexers in plain text, but this is not a weakening of securiy posture. In the fuure -when [ECH] is ready the muxer info can be protected too. +when [ECH] is ready the multiplexer info can be protected too. The early data in Noise handshake is only sent afer the peers establish a shared key, in the second and third handshake messages in the XX pattern. So -the early data is encrypted and the muxer info carried over is protected. +the early data is encrypted and the multiplexer info carried over is protected. These is no security weakening in this case either. @@ -236,13 +239,13 @@ These is no security weakening in this case either. This feature aggregates the multistream-selecion function and security handshake function. From function separation point of view, it introduces coupling between different functions. But the argument is that in the case of -libp2p, the muxer and security are always needed at the same time, and it is a +libp2p, the multiplexer and security are always needed at the same time, and it is a small price to pay to gain efficiency by reducing one RTT. ## Alternative options considered -Instead of ALPN for muxer selection to reduce RTT, other options such as TLS +Instead of ALPN for multiplexer selection to reduce RTT, other options such as TLS extension and X.509 extension are considered. The pros and cons are explored and the discussion details can be found at [#454]. From 5192ad11fa1611d617cc200eff9d872c63e102f3 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Sun, 16 Oct 2022 14:04:59 -0700 Subject: [PATCH 23/50] Revise some typos --- connections/muxer-sel-in-sec-handshake.md | 37 ++++++++++++----------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 61058b3fb..a7b824be9 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -39,7 +39,7 @@ and spec status. ## Overview -This document discribes an imporvement on the stream multiplexer negotiation +This document describes an improvement on the stream multiplexer negotiation process. The goal of the improvement is to reduce the number of RTTs that takes to negotiate the stream multiplexer for a transport that does not natively support stream multiplexing. The solution relies on the ability of the security @@ -61,12 +61,12 @@ pervious libp2p versions which do not support this improved approach. The current connection upgrade process is described in detail in [connections]. As shown in this [sequence-chart], after a network connection is established, -the following will happen to upgrade the conntection to a secured and stream- -multiplexed onnection. +the following will happen to upgrade the connection to a secured and stream- +multiplexed connection. 1. The multistream-selection protocol is run over the connection to select the security protocol to be used. -2. The selected security protocol performs handshaking and establishs a secure +2. The selected security protocol performs handshaking and establishes a secure tunnel 3. The multistream-selection protocol then will run again for multiplexer negotiation. @@ -95,7 +95,7 @@ to negotiate the multiplexer. ### Multiplexer negotiation over TLS When the security protocol selected by the upgrader is TLS, the [ALPN] -extesion of TLS handshake is used to select the multiplexer. +extension of TLS handshake is used to select the multiplexer. With ALPN, the client sends the list of supported application protocols as part of the TLS ClientHello message. The server chooses @@ -111,20 +111,21 @@ field. An example list as following: ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] -The multiplexer list is ordered by preference, with the most prefered multiplexer at -the beginning. The "libp2p" protocol code MUST always be the last item in the -multiplexer list . See [#tls-case] for details on the special "libp2p" protocol code. +The multiplexer list is ordered by preference, with the most preferred +multiplexer at the beginning. The "libp2p" protocol code MUST always be the +last item in the multiplexer list . See [#tls-case] for details on the special +"libp2p" protocol code. -The server SHOULD choose the supported protocol by going through its prefered +The server SHOULD choose the supported protocol by going through its preferred protocol list and search if the protocol is supported by the client too. If no -mutually supported protcol is found the TLS handshake will fail. +mutually supported protocol is found the TLS handshake will fail. -If the selected item from the multiplexer list is "libp2p" then the multiplexer negotiation -process returns an empty result, and the multistream-selection protocol MUST be -run to negotiate the multiplexer. +If the selected item from the multiplexer list is "libp2p" then the multiplexer +negotiation process returns an empty result, and the multistream-selection +protocol MUST be run to negotiate the multiplexer. -### multiplexer negotiation over Noise +### Multiplexer negotiation over Noise The libp2p Noise Specification allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the second and third message of @@ -133,8 +134,8 @@ The second message carries early data in the form of a list of multiplexers supp by the responder, ordered by preference. The initiator sends its supported multiplexer list in the third message to the responder. After the Noise handshake process is fully done, the initiator and responder will both process the -received eraly data and select the multiplexer to be used, they both iterate through -the initiator's prefered multiplexer list in order, and if any multiplexer is also +received early data and select the multiplexer to be used, they both iterate through +the initiator's preferred multiplexer list in order, and if any multiplexer is also supported by the responder, that multiplexer is selected. If no mutually supported multiplexer is found, the multiplexer negotiation process MUST fall back to multistream -selection protocol. @@ -204,10 +205,10 @@ do not support this sepcification. The multiplexer list carried in TLS ALPN extension field is part of the ClientHello message which is not encrypted. This feature will expose the supported multiplexers -in plain text, but this is not a weakening of securiy posture. In the fuure +in plain text, but this is not a weakening of security posture. In the future when [ECH] is ready the multiplexer info can be protected too. -The early data in Noise handshake is only sent afer the peers establish a +The early data in Noise handshake is only sent after the peers establish a shared key, in the second and third handshake messages in the XX pattern. So the early data is encrypted and the multiplexer info carried over is protected. These is no security weakening in this case either. From 4ff74a700a53bda6631acc386e1cce4f5d873a6e Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 17 Oct 2022 11:19:42 -0700 Subject: [PATCH 24/50] Revise the Noise selection process so that the selection of muxer is based on the responder's priority and fix some typos --- connections/muxer-sel-in-sec-handshake.md | 31 ++++++++++++----------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index a7b824be9..ef9920269 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -49,10 +49,10 @@ handshake. With this improvement, the negotiation of the stream multiplexer doesn't consume any additional roundtrips. This feature aggregates the multiplexer negotiation function and security -handshake function. It introduces coupling between different functions. +handshake function. It introduces coupling between those two functions. The improved multiplexer negotiation approach MUST be interoperable with -pervious libp2p versions which do not support this improved approach. +pervious libp2p versions which do not support this improvement. ## Design @@ -68,16 +68,16 @@ multiplexed connection. security protocol to be used. 2. The selected security protocol performs handshaking and establishes a secure tunnel -3. The multistream-selection protocol then will run again for multiplexer +3. The multistream-selection protocol then will run again for stream multiplexer negotiation. -4. The selected multiplexer is then used on the secured connection. +4. The selected stream multiplexer is then used on the secured connection. ## Improved multiplexer negotiation The security protocol's ability of supporting higher level abstract protocol negotiation (for example, TLS's support of ALPN, and Noise's support of Early Data) makes it possible to collapse the step 2 and step 3 in the previous -section into one step. multiplexer negotiation can be performed as part of the +section into one step. Multiplexer negotiation can be performed as part of the security protocol handshake, thus there is no need to perform another mutistream -selection negotiation for multiplexer negotiation. @@ -105,9 +105,10 @@ extension of TLS handshake is used to select the multiplexer. round-trips, and allows the server to associate a different certificate with each application protocol, if desired. -For the purpose of multiplexer negotiation, the types of multiplexers are coded as protocol -names in the form of a list of strings, and inserted in the ALPN extension -field. An example list as following: +For the purpose of multiplexer negotiation, the types of multiplexers are coded +as protocol names in the form of a list of strings, and inserted in the ALPN +extension field. + An example list: ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] @@ -135,22 +136,22 @@ by the responder, ordered by preference. The initiator sends its supported multiplexer list in the third message to the responder. After the Noise handshake process is fully done, the initiator and responder will both process the received early data and select the multiplexer to be used, they both iterate through -the initiator's preferred multiplexer list in order, and if any multiplexer is also -supported by the responder, that multiplexer is selected. If no mutually supported +the responder's preferred multiplexer list in order, and if the multiplexer is also +supported by the initiator, that multiplexer is selected. If no mutually supported multiplexer is found, the multiplexer negotiation process MUST fall back to multistream -selection protocol. Example: Noise handshake between peers that have a mutually supported multiplexer. - Initiator supports: ["yamux/1.0.0", "/mplex/6.7.0"] - Responder supports: ["/mplex/6.7.0", "yamux/1.0.0"] + Initiator supports: ["/yamux/1.0.0", "/mplex/6.7.0"] + Responder supports: ["/mplex/6.7.0", "/yamux/1.0.0"] XX: -> e - <- e, ee, s, es, ["/mplex/6.7.0", "yamux/1.0.0"] - -> s, se, ["yamux/1.0.0", "/mplex/6.7.0"] + <- e, ee, s, es, ["/mplex/6.7.0", "/yamux/1.0.0"] + -> s, se, ["/yamux/1.0.0", "/mplex/6.7.0"] After handshake is done, both parties can arrive on the same conclusion - and select "yamux/1.0.0" as the multiplexer to use. + and select "/mplex/6.7.0" as the multiplexer to use. Example: Noise handshake between peers that don't have mutually supported multiplexers. From f69b691df98e4fc28f57eb07a83ac75d773c1830 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 17 Oct 2022 13:52:16 -0700 Subject: [PATCH 25/50] Editorial --- connections/muxer-sel-in-sec-handshake.md | 45 +++++++++++++---------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index ef9920269..e17978d86 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -131,17 +131,21 @@ protocol MUST be run to negotiate the multiplexer. The libp2p Noise Specification allows the Noise handshake process to carry early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. -The second message carries early data in the form of a list of multiplexers supported -by the responder, ordered by preference. The initiator sends its supported -multiplexer list in the third message to the responder. After the Noise handshake -process is fully done, the initiator and responder will both process the -received early data and select the multiplexer to be used, they both iterate through -the responder's preferred multiplexer list in order, and if the multiplexer is also -supported by the initiator, that multiplexer is selected. If no mutually supported -multiplexer is found, the multiplexer negotiation process MUST fall back to multistream --selection protocol. - -Example: Noise handshake between peers that have a mutually supported multiplexer. +The second message carries early data in the form of a list of multiplexers +supported by the responder, ordered by preference. The initiator sends its +supported multiplexer list in the third message to the responder. + +For security reasons the early data is not processed until the Noise handshake +is finished. After the Noise handshake process is fully done, the initiator and +responder will both process the received early data and select the multiplexer +to be used. They both iterate through +the responder's preferred multiplexer list in order, and if the multiplexer is +also supported by the initiator, that multiplexer is selected. If no mutually +supported multiplexer is found, the multiplexer negotiation process MUST fall +back to multistream-selection protocol. + +Example: Noise handshake between peers that have a mutually supported +multiplexer. Initiator supports: ["/yamux/1.0.0", "/mplex/6.7.0"] Responder supports: ["/mplex/6.7.0", "/yamux/1.0.0"] @@ -168,7 +172,7 @@ multiplexers. The multiplexer selection logic is run after the Noise handshake has finished mutual authentication of the peers. The format of he early data is specified in -the protobuf in the [Early-data-specification] section. +the protobuf definition found in the [Early-data-specification] section. The details of the early data message format can be find in [Noise-handshake-payload] @@ -204,10 +208,11 @@ do not support this sepcification. ## Security -The multiplexer list carried in TLS ALPN extension field is part of the ClientHello -message which is not encrypted. This feature will expose the supported multiplexers -in plain text, but this is not a weakening of security posture. In the future -when [ECH] is ready the multiplexer info can be protected too. +The multiplexer list carried in TLS ALPN extension field is part of the +ClientHello message which is not encrypted. This feature will expose the +supported multiplexers in plain text, but this is not a weakening of security +posture. In the future when [ECH] is ready the multiplexer info can be +protected too. The early data in Noise handshake is only sent after the peers establish a shared key, in the second and third handshake messages in the XX pattern. So @@ -220,14 +225,14 @@ These is no security weakening in this case either. This feature aggregates the multistream-selecion function and security handshake function. From function separation point of view, it introduces coupling between different functions. But the argument is that in the case of -libp2p, the multiplexer and security are always needed at the same time, and it is a -small price to pay to gain efficiency by reducing one RTT. +libp2p, the multiplexer and security are always needed at the same time, and +it is a small price to pay to gain efficiency by reducing one RTT. ## Alternative options considered -Instead of ALPN for multiplexer selection to reduce RTT, other options such as TLS -extension and X.509 extension are considered. The pros and cons are explored +Instead of ALPN for multiplexer selection to reduce RTT, other options such as +TLS extension and X.509 extension are considered. The pros and cons are explored and the discussion details can be found at [#454]. From 8e51f4645ad83cb1ca17beed5e7b3652580c5f18 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 17 Oct 2022 14:06:30 -0700 Subject: [PATCH 26/50] formatting --- connections/muxer-sel-in-sec-handshake.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index e17978d86..f10167c65 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -187,7 +187,7 @@ supported multiplexer sets is always satisfied. When one peer runs the old version and the other peer runs the version that supports this feature, the negotiated protocol is "libp2p". -In the case "libp2p" is the result of TLS ALPN, an empty result MUST be +In the case that "libp2p" is the result of TLS ALPN, an empty result MUST be returned to the upgrade process to indicate that no multiplexer was selected. And the upgrade process MUST fall back to the multistream-selection protocol to to negotiate the multiplexer to be selected. This fallback behavior ensures @@ -201,10 +201,10 @@ version that supports this feature talks to an older version which does not support this feature, the multiplexer selection process on the new version runs against an empty string and will return empty multiplexer selection result. -In the case an empty multiplexer selection result is returned, the upgrade process -MUST fall back to the multistream-selection protocol to select the multiplexer. -This fallback behavior ensures backward compatibility with previous versions that -do not support this sepcification. +In the case an empty multiplexer selection result is returned, the upgrade +process MUST fall back to the multistream-selection protocol to select the +multiplexer. This fallback behavior ensures backward compatibility with +previous versions that do not support this sepcification. ## Security @@ -247,9 +247,3 @@ and the discussion details can be found at [#454]. [#454]: https://github.com/libp2p/specs/issues/454 [Noise-handshake-payload]: https://github.com/libp2p/specs/blob/b0818fa956f9940a7cdee18198e0daf1645d8276/noise/README.md#libp2p-data-in-handshake-messages - - - - - - From eb4e697fb19fd968812a55728fee423a326fd6bb Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 18 Oct 2022 15:18:50 -0700 Subject: [PATCH 27/50] Update muxer-sel-in-sec-handshake.md --- connections/muxer-sel-in-sec-handshake.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index f10167c65..5567b0229 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -34,7 +34,6 @@ and spec status. - [TLS case](#tls-case) - [Noise case](#noise-case) - [Security](#security) - - [Protocol coupling](#protocol-coupling) - [Alternative options considered](#alternative-options-considered) ## Overview @@ -204,7 +203,7 @@ against an empty string and will return empty multiplexer selection result. In the case an empty multiplexer selection result is returned, the upgrade process MUST fall back to the multistream-selection protocol to select the multiplexer. This fallback behavior ensures backward compatibility with -previous versions that do not support this sepcification. +previous versions that do not support this specification. ## Security @@ -220,15 +219,6 @@ the early data is encrypted and the multiplexer info carried over is protected. These is no security weakening in this case either. -## Protocol coupling - -This feature aggregates the multistream-selecion function and security -handshake function. From function separation point of view, it introduces -coupling between different functions. But the argument is that in the case of -libp2p, the multiplexer and security are always needed at the same time, and -it is a small price to pay to gain efficiency by reducing one RTT. - - ## Alternative options considered Instead of ALPN for multiplexer selection to reduce RTT, other options such as From ef8657d0d713d2f04e7dcf10d18a1f7cb5ea25b0 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Tue, 18 Oct 2022 15:26:26 -0700 Subject: [PATCH 28/50] Update muxer-sel-in-sec-handshake.md --- connections/muxer-sel-in-sec-handshake.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 5567b0229..b4ed57361 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -29,7 +29,6 @@ and spec status. - [Improved multiplexer negotiation](#improved-multiplexer-negotiation) - [Multiplexer negotiation over TLS](#multiplexer-negotiation-over-tls) - [Multiplexer negotiation over Noise](#multiplexer-negotiation-over-noise) - - [Early data specification](#early-data-specification) - [Cross version support](#cross-version-support) - [TLS case](#tls-case) - [Noise case](#noise-case) @@ -39,8 +38,8 @@ and spec status. ## Overview This document describes an improvement on the stream multiplexer negotiation -process. The goal of the improvement is to reduce the number of RTTs that takes -to negotiate the stream multiplexer for a transport that does not natively +process. The goal of the improvement is to reduce the number of RTTs to +negotiate the stream multiplexer for a transport that does not natively support stream multiplexing. The solution relies on the ability of the security protocol's handshake process to negotiate higher level protocols, which enables the multiplexer negotiation to be carried out along with the security protocol @@ -51,7 +50,7 @@ This feature aggregates the multiplexer negotiation function and security handshake function. It introduces coupling between those two functions. The improved multiplexer negotiation approach MUST be interoperable with -pervious libp2p versions which do not support this improvement. +previous libp2p versions which do not support this improvement. ## Design @@ -77,7 +76,7 @@ The security protocol's ability of supporting higher level abstract protocol negotiation (for example, TLS's support of ALPN, and Noise's support of Early Data) makes it possible to collapse the step 2 and step 3 in the previous section into one step. Multiplexer negotiation can be performed as part of the -security protocol handshake, thus there is no need to perform another mutistream +security protocol handshake, thus there is no need to perform another multistream -selection negotiation for multiplexer negotiation. In order to achieve the above stated goal, each candidate multiplexer will be @@ -170,7 +169,7 @@ multiplexers. supported multiplexer, and falls back to multistream-selection protocol. The multiplexer selection logic is run after the Noise handshake has finished -mutual authentication of the peers. The format of he early data is specified in +mutual authentication of the peers. The format of the early data is specified in the protobuf definition found in the [Early-data-specification] section. The details of the early data message format can be find in @@ -188,7 +187,7 @@ negotiated protocol is "libp2p". In the case that "libp2p" is the result of TLS ALPN, an empty result MUST be returned to the upgrade process to indicate that no multiplexer was selected. -And the upgrade process MUST fall back to the multistream-selection protocol to +And the upgrade process MUST fall back to the multistream-selection protocol to negotiate the multiplexer to be selected. This fallback behavior ensures backward compatibility with previous versions that do not support the feature specified by this document. @@ -207,7 +206,7 @@ previous versions that do not support this specification. ## Security -The multiplexer list carried in TLS ALPN extension field is part of the +The multiplexer list carried in the TLS ALPN extension field is part of the ClientHello message which is not encrypted. This feature will expose the supported multiplexers in plain text, but this is not a weakening of security posture. In the future when [ECH] is ready the multiplexer info can be @@ -216,7 +215,7 @@ protected too. The early data in Noise handshake is only sent after the peers establish a shared key, in the second and third handshake messages in the XX pattern. So the early data is encrypted and the multiplexer info carried over is protected. -These is no security weakening in this case either. +There is no security weakening in this case either. ## Alternative options considered From 8296442ab045196d233362a3b4102769d8df146e Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Wed, 19 Oct 2022 10:54:55 -0700 Subject: [PATCH 29/50] Update muxer-sel-in-sec-handshake.md Consolidate some sections and clarify backward compatibility section. --- connections/muxer-sel-in-sec-handshake.md | 59 +++++++++-------------- 1 file changed, 23 insertions(+), 36 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index b4ed57361..c21bf151f 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -29,9 +29,6 @@ and spec status. - [Improved multiplexer negotiation](#improved-multiplexer-negotiation) - [Multiplexer negotiation over TLS](#multiplexer-negotiation-over-tls) - [Multiplexer negotiation over Noise](#multiplexer-negotiation-over-noise) - - [Cross version support](#cross-version-support) - - [TLS case](#tls-case) - - [Noise case](#noise-case) - [Security](#security) - [Alternative options considered](#alternative-options-considered) @@ -112,8 +109,20 @@ extension field. The multiplexer list is ordered by preference, with the most preferred multiplexer at the beginning. The "libp2p" protocol code MUST always be the -last item in the multiplexer list . See [#tls-case] for details on the special -"libp2p" protocol code. +last item in the multiplexer list. The reason for adding this special +protocol code is to ensure backward compatibility. In the previous versions +that do not support this feature, the ALPN extension field is alwasy populated +with a key "libp2p". By appending the key of "libp2p" to the end of the +supported multiplexer list, the overlap of the peer's supported ALPN protocols +is always satisfied when different versions of libp2p are negotiating a TLS +connection. + +In the case that "libp2p" is the result of TLS ALPN, an empty result MUST be +returned to the upgrade process to indicate that no multiplexer was selected. +And the upgrade process MUST fall back to the multistream-selection protocol +to negotiate the multiplexer to be selected. This fallback behavior ensures +backward compatibility with previous versions that do not support the feature +specified by this document. The server SHOULD choose the supported protocol by going through its preferred protocol list and search if the protocol is supported by the client too. If no @@ -136,11 +145,10 @@ supported multiplexer list in the third message to the responder. For security reasons the early data is not processed until the Noise handshake is finished. After the Noise handshake process is fully done, the initiator and responder will both process the received early data and select the multiplexer -to be used. They both iterate through -the responder's preferred multiplexer list in order, and if the multiplexer is -also supported by the initiator, that multiplexer is selected. If no mutually -supported multiplexer is found, the multiplexer negotiation process MUST fall -back to multistream-selection protocol. +to be used. They both iterate through the responder's preferred multiplexer +list in order, and if the multiplexer is also supported by the initiator, that +multiplexer is selected. If no mutually supported multiplexer is found, the +multiplexer negotiation process MUST fall back to multistream-selection protocol. Example: Noise handshake between peers that have a mutually supported multiplexer. @@ -175,34 +183,13 @@ the protobuf definition found in the [Early-data-specification] section. The details of the early data message format can be find in [Noise-handshake-payload] -### TLS case - -In the current version of libp2p, the ALPN extension field is populated with a -key "libp2p". By appending the key of "libp2p" to the end of the supported -multiplexer list, the TLS handshaking process is not broken when peers run -different versions of libp2p, because the minimum overlap of the peer's -supported multiplexer sets is always satisfied. When one peer runs the old -version and the other peer runs the version that supports this feature, the -negotiated protocol is "libp2p". - -In the case that "libp2p" is the result of TLS ALPN, an empty result MUST be -returned to the upgrade process to indicate that no multiplexer was selected. -And the upgrade process MUST fall back to the multistream-selection protocol -to negotiate the multiplexer to be selected. This fallback behavior ensures -backward compatibility with previous versions that do not support the feature -specified by this document. - -### Noise case - -The existing version of libp2p Noise handshake carries empty early data. When a +In the previous versions that do not support this feature, the Noise handshake +messages carry an empty field of muxer list in the early data extension. When a version that supports this feature talks to an older version which does not support this feature, the multiplexer selection process on the new version runs -against an empty string and will return empty multiplexer selection result. - -In the case an empty multiplexer selection result is returned, the upgrade -process MUST fall back to the multistream-selection protocol to select the -multiplexer. This fallback behavior ensures backward compatibility with -previous versions that do not support this specification. +against an empty list and will return empty multiplexer selection result. +In this case, backward compatibility is achieved by falling back to the +multistream-selection process. ## Security From 0fc4452f5ada77a323de636bb36175c3aca57f46 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Wed, 19 Oct 2022 14:56:44 -0700 Subject: [PATCH 30/50] Consolidate some sections again and simplify some descriptiosn. --- connections/Temp.md | 853 ++++++++++++++++++++++ connections/muxer-sel-in-sec-handshake.md | 82 +-- 2 files changed, 889 insertions(+), 46 deletions(-) create mode 100644 connections/Temp.md diff --git a/connections/Temp.md b/connections/Temp.md new file mode 100644 index 000000000..eac714b2f --- /dev/null +++ b/connections/Temp.md @@ -0,0 +1,853 @@ + + +#Testground multi-dimensional test matrix + + +### Tests are to be composed from the information extracted out of the resource files. + +An example resource file entry may look like this: + + + [[groups]] + + + # go v0.42 + + + GoVersion = '1.18' + + + Modfile = "go.v0.22.mod" + + + Selector = 'v0.42' + + + Implementation = 'go' + + + SupportedTransports = ["tcp", "quic", "webrtc"] + + + SupportedSecurityProtos = [“tls”, “noise”] + + + SupportedMuxers = ["yamux", “mplex”] + + +### A test peer/host is customized by the following parameters: + + testHost = Host(implementation, version, transport, securityProto, supportedMuxers) + + +### A test case is composed by two or more test hosts: + + testInstance = TestInstance(testHost-1, testHost2, …) + + +### Go transport list: + + Go-libp2p-transports = [“TCP”, “QUIC”, “Webtransport”, “Websocket”] + + +### Rust transport list: + + Rust-libp2p-transports = [“TCP”, “WebRTC”] + + +### JS transport list: + + JS-libp2p-transports[“ToDo”] + +Test Matrix + +Test matrix for libp2p multi dimensional tests. (Test cases should also be run with source/destination flipped) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Test case + Source Host + Run +

+Test +

Destination Host + Expected Res +
+ Imp + Ver + Trans + Sec + Muxs + Imp + Ver + Trans + Sec + Muxs + Muxer + RTT +
1 + go + master + tcp + tls + ML1 + X + go + 1 + tcp + tls + ML1 + M1 + rtt-1 +
2 + go + cur + tcp + tls + ML2 + M2 + rtt-1 +
3 + go + cur-1 + tcp + tls + ML1 + M1 + rtt +
4 + go + cur-2 + tcp + tls + ML1 + M1 + rtt +
5 + go + cur-3 + tcp + tls + ML1 + M1 + rtt +
6 + go + cur + tcp + noise + ML1 + X + go + cur + tcp + noise + ML1 + M1 + rtt-1 +
7 + go + cur + tcp + noise + ML-2 + M1 + rtt-1 +
8 + go + cur-1 + tcp + noise + ML1 + M1 + rtt +
9 + go + cur-2 + tcp + noise + ML1 + M1 + rtt +
10 + go + cur-3 + tcp + noise + ML1 + M1 + rtt +
11 + go + cur + tcp + noise + ML1 + X + rust + cur + tcp + noise + ML1 + M1 + rtt +
12 + rust + cur-1 + tcp + noise + ML1 + M1 + rtt +
13 + rust + cur-2 + tcp + noise + ML1 + M1 + rtt +
14 + rust + cur-3 + tcp + noise + ML1 + M1 + rtt +
15 + go + cur + tcp + tls + ML1 + X + JS + cur + tcp + noise + ML1 + M1 + rtt +
16 + JS + cur + tcp + noise + ML-2 + M1 + rtt +
17 + JS + cur-1 + tcp + noise + ML1 + M1 + rtt +
18 + JS + cur-2 + tcp + noise + ML1 + M1 + rtt +
19 + JS + cur-3 + tcp + noise + ML1 + M1 + rtt +
+ go + cur + QUIC + - + - + X + go + cur + QUIC + - + - + - + +
+ go + cur-1 + QUIC + - + - + - + +
+ go + cur-2 + QUIC + - + - + - + +
+ go + cur-3 + QUIC + - + - + - + +
+ go + cur + WebTransport + - + - + X + go + cur + WT + - + - + - + +
+ go + cur-1 + WT + - + - + - + +
+ go + cur-2 + WT + - + - + - + +
+ go + cur-3 + WT + - + - + - + +
+ go + cur + WS + - + - + X + go + cur + WS + - + - + - + +
+ go + cur-1 + WS + - + - + - + +
+ go + cur-2 + WS + - + - + - + +
+ go + cur-3 + WS + - + - + - + +
+ rust + cur + TCP + noise + - + X + JS + cur + TCP + noise + - + + +
+ JS + + + + + + +
+ + + + + + + +
+ + + + + + + + + + + + + +
+ + +ML1 = ["/yamux/1.0.0", "/mplex/6.7.0"] M1 = “/yamux/1.0.0” , M2 = “/mplex/6.7.0” + +ML2 = ["/mplex/6.7.0", "/yamux/1.0.0"] ML3 = [“/mplex/6.7.0”] diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index c21bf151f..566298065 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -73,8 +73,8 @@ The security protocol's ability of supporting higher level abstract protocol negotiation (for example, TLS's support of ALPN, and Noise's support of Early Data) makes it possible to collapse the step 2 and step 3 in the previous section into one step. Multiplexer negotiation can be performed as part of the -security protocol handshake, thus there is no need to perform another multistream --selection negotiation for multiplexer negotiation. +security protocol handshake, thus there is no need to perform another +multistream-selection negotiation for multiplexer negotiation. In order to achieve the above stated goal, each candidate multiplexer will be represented by a protocol name/code, and the candidate multiplexers are supplied @@ -86,7 +86,6 @@ multiplexer. If no agreement is reached upon by the client and server then the connection upgrade process MUST fall back to the multistream-selection protocol to negotiate the multiplexer. - ### Multiplexer negotiation over TLS When the security protocol selected by the upgrader is TLS, the [ALPN] @@ -108,47 +107,40 @@ extension field. ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] The multiplexer list is ordered by preference, with the most preferred -multiplexer at the beginning. The "libp2p" protocol code MUST always be the -last item in the multiplexer list. The reason for adding this special -protocol code is to ensure backward compatibility. In the previous versions -that do not support this feature, the ALPN extension field is alwasy populated -with a key "libp2p". By appending the key of "libp2p" to the end of the -supported multiplexer list, the overlap of the peer's supported ALPN protocols -is always satisfied when different versions of libp2p are negotiating a TLS -connection. - -In the case that "libp2p" is the result of TLS ALPN, an empty result MUST be -returned to the upgrade process to indicate that no multiplexer was selected. -And the upgrade process MUST fall back to the multistream-selection protocol -to negotiate the multiplexer to be selected. This fallback behavior ensures -backward compatibility with previous versions that do not support the feature -specified by this document. - -The server SHOULD choose the supported protocol by going through its preferred -protocol list and search if the protocol is supported by the client too. If no -mutually supported protocol is found the TLS handshake will fail. - -If the selected item from the multiplexer list is "libp2p" then the multiplexer -negotiation process returns an empty result, and the multistream-selection -protocol MUST be run to negotiate the multiplexer. - +multiplexer at the beginning. The server SHOULD choose the supported protocol by +going through its preferred protocol list and search if the protocol is +supported by the client too. If no mutually supported protocol is found the TLS +handshake will fail. + +The "libp2p" protocol code MUST always be the last item in the multiplexer list. +The reason for adding this special protocol code is to ensure backward +compatibility. In the previous versions that do not support this feature, the +ALPN extension field is alwasy populated with a key "libp2p". By appending the +key of "libp2p" to the end of the supported multiplexer list, the overlap of the +peer's supported ALPN protocols is always guaranteed when different versions of +libp2p are negotiating a TLS connection. + +In the case that "libp2p" is the result of TLS ALPN, The upgrade process MUST +fall back to the multistream-selection protocol to negotiate the multiplexer to +be used. This fallback behavior ensures backward compatibility. ### Multiplexer negotiation over Noise -The libp2p Noise Specification allows the Noise handshake process to carry +The libp2p Noise Specification allows the Noise handshake messages to carry early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. The second message carries early data in the form of a list of multiplexers supported by the responder, ordered by preference. The initiator sends its -supported multiplexer list in the third message to the responder. +supported multiplexer list in the third message of the handshake process. -For security reasons the early data is not processed until the Noise handshake -is finished. After the Noise handshake process is fully done, the initiator and -responder will both process the received early data and select the multiplexer -to be used. They both iterate through the responder's preferred multiplexer -list in order, and if the multiplexer is also supported by the initiator, that -multiplexer is selected. If no mutually supported multiplexer is found, the -multiplexer negotiation process MUST fall back to multistream-selection protocol. +For security reasons the early data SHALL not be processed until the Noise +handshake is finished. After the Noise handshake process is fully done, the +initiator and responder will both process the received early data and select the +multiplexer to be used. They both iterate through the responder's preferred +multiplexer list in order, and if the multiplexer is also supported by the +initiator, that multiplexer is selected. If no mutually supported multiplexer is +found, the multiplexer negotiation process MUST fall back to multistream +-selection protocol. Example: Noise handshake between peers that have a mutually supported multiplexer. @@ -180,28 +172,26 @@ The multiplexer selection logic is run after the Noise handshake has finished mutual authentication of the peers. The format of the early data is specified in the protobuf definition found in the [Early-data-specification] section. -The details of the early data message format can be find in -[Noise-handshake-payload] +The details of the early data message format can be find in [Noise-handshake-payload] In the previous versions that do not support this feature, the Noise handshake messages carry an empty field of muxer list in the early data extension. When a version that supports this feature talks to an older version which does not -support this feature, the multiplexer selection process on the new version runs -against an empty list and will return empty multiplexer selection result. -In this case, backward compatibility is achieved by falling back to the -multistream-selection process. +support this feature, the multiplexer selection process on both peers will +generate an empty list and they MUST fall back to the multistream-selection +process to ensure backward compatibility. ## Security The multiplexer list carried in the TLS ALPN extension field is part of the ClientHello message which is not encrypted. This feature will expose the supported multiplexers in plain text, but this is not a weakening of security -posture. In the future when [ECH] is ready the multiplexer info can be -protected too. +posture. In the future when [ECH] is ready the multiplexer info can be protected +too. The early data in Noise handshake is only sent after the peers establish a -shared key, in the second and third handshake messages in the XX pattern. So -the early data is encrypted and the multiplexer info carried over is protected. +shared key, in the second and third handshake messages in the XX pattern. So the +early data is encrypted and the multiplexer info carried over is protected. There is no security weakening in this case either. From a11ff1d4ab10dbba1b00e3f66e873e4056ad8162 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Wed, 19 Oct 2022 15:00:20 -0700 Subject: [PATCH 31/50] remove accidentally checked file --- connections/Temp.md | 853 -------------------------------------------- 1 file changed, 853 deletions(-) delete mode 100644 connections/Temp.md diff --git a/connections/Temp.md b/connections/Temp.md deleted file mode 100644 index eac714b2f..000000000 --- a/connections/Temp.md +++ /dev/null @@ -1,853 +0,0 @@ - - -#Testground multi-dimensional test matrix - - -### Tests are to be composed from the information extracted out of the resource files. - -An example resource file entry may look like this: - - - [[groups]] - - - # go v0.42 - - - GoVersion = '1.18' - - - Modfile = "go.v0.22.mod" - - - Selector = 'v0.42' - - - Implementation = 'go' - - - SupportedTransports = ["tcp", "quic", "webrtc"] - - - SupportedSecurityProtos = [“tls”, “noise”] - - - SupportedMuxers = ["yamux", “mplex”] - - -### A test peer/host is customized by the following parameters: - - testHost = Host(implementation, version, transport, securityProto, supportedMuxers) - - -### A test case is composed by two or more test hosts: - - testInstance = TestInstance(testHost-1, testHost2, …) - - -### Go transport list: - - Go-libp2p-transports = [“TCP”, “QUIC”, “Webtransport”, “Websocket”] - - -### Rust transport list: - - Rust-libp2p-transports = [“TCP”, “WebRTC”] - - -### JS transport list: - - JS-libp2p-transports[“ToDo”] - -Test Matrix - -Test matrix for libp2p multi dimensional tests. (Test cases should also be run with source/destination flipped) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Test case - Source Host - Run -

-Test -

Destination Host - Expected Res -
- Imp - Ver - Trans - Sec - Muxs - Imp - Ver - Trans - Sec - Muxs - Muxer - RTT -
1 - go - master - tcp - tls - ML1 - X - go - 1 - tcp - tls - ML1 - M1 - rtt-1 -
2 - go - cur - tcp - tls - ML2 - M2 - rtt-1 -
3 - go - cur-1 - tcp - tls - ML1 - M1 - rtt -
4 - go - cur-2 - tcp - tls - ML1 - M1 - rtt -
5 - go - cur-3 - tcp - tls - ML1 - M1 - rtt -
6 - go - cur - tcp - noise - ML1 - X - go - cur - tcp - noise - ML1 - M1 - rtt-1 -
7 - go - cur - tcp - noise - ML-2 - M1 - rtt-1 -
8 - go - cur-1 - tcp - noise - ML1 - M1 - rtt -
9 - go - cur-2 - tcp - noise - ML1 - M1 - rtt -
10 - go - cur-3 - tcp - noise - ML1 - M1 - rtt -
11 - go - cur - tcp - noise - ML1 - X - rust - cur - tcp - noise - ML1 - M1 - rtt -
12 - rust - cur-1 - tcp - noise - ML1 - M1 - rtt -
13 - rust - cur-2 - tcp - noise - ML1 - M1 - rtt -
14 - rust - cur-3 - tcp - noise - ML1 - M1 - rtt -
15 - go - cur - tcp - tls - ML1 - X - JS - cur - tcp - noise - ML1 - M1 - rtt -
16 - JS - cur - tcp - noise - ML-2 - M1 - rtt -
17 - JS - cur-1 - tcp - noise - ML1 - M1 - rtt -
18 - JS - cur-2 - tcp - noise - ML1 - M1 - rtt -
19 - JS - cur-3 - tcp - noise - ML1 - M1 - rtt -
- go - cur - QUIC - - - - - X - go - cur - QUIC - - - - - - - -
- go - cur-1 - QUIC - - - - - - - -
- go - cur-2 - QUIC - - - - - - - -
- go - cur-3 - QUIC - - - - - - - -
- go - cur - WebTransport - - - - - X - go - cur - WT - - - - - - - -
- go - cur-1 - WT - - - - - - - -
- go - cur-2 - WT - - - - - - - -
- go - cur-3 - WT - - - - - - - -
- go - cur - WS - - - - - X - go - cur - WS - - - - - - - -
- go - cur-1 - WS - - - - - - - -
- go - cur-2 - WS - - - - - - - -
- go - cur-3 - WS - - - - - - - -
- rust - cur - TCP - noise - - - X - JS - cur - TCP - noise - - - - -
- JS - - - - - - -
- - - - - - - -
- - - - - - - - - - - - - -
- - -ML1 = ["/yamux/1.0.0", "/mplex/6.7.0"] M1 = “/yamux/1.0.0” , M2 = “/mplex/6.7.0” - -ML2 = ["/mplex/6.7.0", "/yamux/1.0.0"] ML3 = [“/mplex/6.7.0”] From b4ce114859dad4f3fc278a4d1fe2cba3cc99a254 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Wed, 19 Oct 2022 15:05:02 -0700 Subject: [PATCH 32/50] Editorial changes --- connections/muxer-sel-in-sec-handshake.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 566298065..a3a92ff14 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -168,11 +168,10 @@ multiplexers. After handshaking is done, early data processing will find no mutually supported multiplexer, and falls back to multistream-selection protocol. -The multiplexer selection logic is run after the Noise handshake has finished -mutual authentication of the peers. The format of the early data is specified in -the protobuf definition found in the [Early-data-specification] section. +The multiplexer selection logic SHOULD run after the Noise handshake has +finished mutual authentication of the peers to enhance security. -The details of the early data message format can be find in [Noise-handshake-payload] +The format of the early data is specified in [Noise-handshake-payload] In the previous versions that do not support this feature, the Noise handshake messages carry an empty field of muxer list in the early data extension. When a From 9b11a6814c43f7473fdfde46afc2823f7263575d Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Wed, 9 Nov 2022 14:28:35 -0800 Subject: [PATCH 33/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index a3a92ff14..1a04dbfe7 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -173,12 +173,6 @@ finished mutual authentication of the peers to enhance security. The format of the early data is specified in [Noise-handshake-payload] -In the previous versions that do not support this feature, the Noise handshake -messages carry an empty field of muxer list in the early data extension. When a -version that supports this feature talks to an older version which does not -support this feature, the multiplexer selection process on both peers will -generate an empty list and they MUST fall back to the multistream-selection -process to ensure backward compatibility. ## Security From 002e37f63ad0159ea68ff1d223030d297b534648 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 14 Nov 2022 11:17:21 -0800 Subject: [PATCH 34/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 1a04dbfe7..f92d564c8 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -91,13 +91,10 @@ to negotiate the multiplexer. When the security protocol selected by the upgrader is TLS, the [ALPN] extension of TLS handshake is used to select the multiplexer. - With ALPN, the client sends the list of supported application - protocols as part of the TLS ClientHello message. The server chooses - a protocol and sends the selected protocol as part of the TLS - ServerHello message. The application protocol negotiation can thus - be accomplished within the TLS handshake, without adding network - round-trips, and allows the server to associate a different - certificate with each application protocol, if desired. +The ALPN TLS extension allows the client to send a list of supported application +protocols as part of the TLS ClientHello message. The server chooses +a protocol and sends the selected protocol as part of the TLS +ServerHello message. For the purpose of multiplexer negotiation, the types of multiplexers are coded as protocol names in the form of a list of strings, and inserted in the ALPN From e3fcb3850d88e64ce03bfef56ed88500775c5db4 Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 14 Nov 2022 11:18:20 -0800 Subject: [PATCH 35/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index f92d564c8..97de9a864 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -67,7 +67,7 @@ tunnel negotiation. 4. The selected stream multiplexer is then used on the secured connection. -## Improved multiplexer negotiation +### Improved multiplexer negotiation The security protocol's ability of supporting higher level abstract protocol negotiation (for example, TLS's support of ALPN, and Noise's support of Early From 4a167d1a0b6642080a7251cd39a7ef7f3186deaa Mon Sep 17 00:00:00 2001 From: julian88110 <111450570+julian88110@users.noreply.github.com> Date: Mon, 14 Nov 2022 11:18:39 -0800 Subject: [PATCH 36/50] Update connections/muxer-sel-in-sec-handshake.md Co-authored-by: Marten Seemann --- connections/muxer-sel-in-sec-handshake.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 97de9a864..bb46101d8 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -34,20 +34,12 @@ and spec status. ## Overview -This document describes an improvement on the stream multiplexer negotiation -process. The goal of the improvement is to reduce the number of RTTs to -negotiate the stream multiplexer for a transport that does not natively -support stream multiplexing. The solution relies on the ability of the security -protocol's handshake process to negotiate higher level protocols, which enables -the multiplexer negotiation to be carried out along with the security protocol -handshake. With this improvement, the negotiation of the stream multiplexer -doesn't consume any additional roundtrips. - -This feature aggregates the multiplexer negotiation function and security -handshake function. It introduces coupling between those two functions. - -The improved multiplexer negotiation approach MUST be interoperable with -previous libp2p versions which do not support this improvement. +Transports that don't support native stream multiplexing (e.g. TCP, WebSocket) negotiate +a stream multiplexer after completion of the cryptographic handshake, as described in [connections]. +Negotiation the stream multiplexer takes one network roundtrip. +This document defines a backwards-compatible optimization, which allows running the +multiplexer negotiation during the cryptographic handshake, thereby reducing the latency of +connection establishment by one roundtrip. ## Design From 3e9586b05b2c4981c8c354e84be754445991860b Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Tue, 15 Nov 2022 21:04:09 -0800 Subject: [PATCH 37/50] Apply some suggestions from code review --- connections/muxer-sel-in-sec-handshake.md | 36 +++++++---------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index bb46101d8..31b115475 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -68,10 +68,6 @@ section into one step. Multiplexer negotiation can be performed as part of the security protocol handshake, thus there is no need to perform another multistream-selection negotiation for multiplexer negotiation. -In order to achieve the above stated goal, each candidate multiplexer will be -represented by a protocol name/code, and the candidate multiplexers are supplied -to the security protocol's handshake process as a list of protocol names. - If the client and server agree upon the common multiplexer to be used, then the result of the multiplexer negotiation is used as the selected stream multiplexer. If no agreement is reached upon by the client and server then the @@ -88,30 +84,20 @@ protocols as part of the TLS ClientHello message. The server chooses a protocol and sends the selected protocol as part of the TLS ServerHello message. -For the purpose of multiplexer negotiation, the types of multiplexers are coded -as protocol names in the form of a list of strings, and inserted in the ALPN -extension field. +For the purpose of multiplexer negotiation, the protocol IDs of the stream +multiplexers are sent, followed by "libp2p". An example list: ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] -The multiplexer list is ordered by preference, with the most preferred -multiplexer at the beginning. The server SHOULD choose the supported protocol by -going through its preferred protocol list and search if the protocol is -supported by the client too. If no mutually supported protocol is found the TLS -handshake will fail. +The multiplexer list is ordered by the client's preference, with the most preferred +multiplexer at the beginning. The server SHOULD pick the first protocol from the +list that it supports. The "libp2p" protocol code MUST always be the last item in the multiplexer list. -The reason for adding this special protocol code is to ensure backward -compatibility. In the previous versions that do not support this feature, the -ALPN extension field is alwasy populated with a key "libp2p". By appending the -key of "libp2p" to the end of the supported multiplexer list, the overlap of the -peer's supported ALPN protocols is always guaranteed when different versions of -libp2p are negotiating a TLS connection. - -In the case that "libp2p" is the result of TLS ALPN, The upgrade process MUST -fall back to the multistream-selection protocol to negotiate the multiplexer to -be used. This fallback behavior ensures backward compatibility. +According to [tls], nodes that don't implement the optimization described in this document +use "libp2p" for their ALPN. If "libp2p" is the result of the ALPN process, nodes MUST use +multistream negotiation of the stream multiplexer as described in [connections]. ### Multiplexer negotiation over Noise @@ -171,10 +157,8 @@ supported multiplexers in plain text, but this is not a weakening of security posture. In the future when [ECH] is ready the multiplexer info can be protected too. -The early data in Noise handshake is only sent after the peers establish a -shared key, in the second and third handshake messages in the XX pattern. So the -early data is encrypted and the multiplexer info carried over is protected. -There is no security weakening in this case either. +Early data in the Noise handshake is sent after the peers have established a +shared key, so an on-path observer won't be able to read the early data. ## Alternative options considered From f682f6bfaedfbc4364530254d444bd2c6b026098 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 16 Nov 2022 18:06:24 +1300 Subject: [PATCH 38/50] add myself to list of authors --- connections/muxer-sel-in-sec-handshake.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 31b115475..3f66348fb 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -5,9 +5,9 @@ |-----------------|---------------|--------|-----------------| | 1A | Working Draft | Active | r1, 2022-09-07 | -Authors: [@julian88110] +Authors: [@julian88110], [@marten-seemann] -Interest Group: [@marten-seemann], [@marcopolo], [@mxinden] +Interest Group: [@marcopolo], [@mxinden] [@marten-seemann]: https://github.com/marten-seemann [@marcopolo]: https://github.com/marcopolo From c07fb79ba5beb5fe7fd8f41ea9d618831b6f026d Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 16 Nov 2022 18:13:14 +1300 Subject: [PATCH 39/50] rewrite the Security section --- connections/muxer-sel-in-sec-handshake.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 3f66348fb..4818fecd1 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -149,16 +149,17 @@ finished mutual authentication of the peers to enhance security. The format of the early data is specified in [Noise-handshake-payload] -## Security +## Privacy -The multiplexer list carried in the TLS ALPN extension field is part of the -ClientHello message which is not encrypted. This feature will expose the -supported multiplexers in plain text, but this is not a weakening of security -posture. In the future when [ECH] is ready the multiplexer info can be protected -too. +The list of multiplexers carried in the TLS ALPN extension field is part of the +ClientHello message which is not encrypted. Using this optimiziation therefore +exposes the list of supported multiplexers to an on-path observer. This leak can +be considered insignificant, since a libp2p node reveals its list of supported +multiplexers to any node that connects to it. -Early data in the Noise handshake is sent after the peers have established a -shared key, so an on-path observer won't be able to read the early data. +The NoiseExtensions sent in the Noise handshake is sent after the peers have +established a shared key, so an on-path observer won't be able to obtain the +list of multiplexers. ## Alternative options considered From 1e7a3c0da44e39d538a35ee69265177c036e8963 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 16 Nov 2022 19:06:30 +1300 Subject: [PATCH 40/50] use the client's preference in Noise --- connections/muxer-sel-in-sec-handshake.md | 37 ++++++++++------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/muxer-sel-in-sec-handshake.md index 4818fecd1..7fd0ab61f 100644 --- a/connections/muxer-sel-in-sec-handshake.md +++ b/connections/muxer-sel-in-sec-handshake.md @@ -36,7 +36,7 @@ and spec status. Transports that don't support native stream multiplexing (e.g. TCP, WebSocket) negotiate a stream multiplexer after completion of the cryptographic handshake, as described in [connections]. -Negotiation the stream multiplexer takes one network roundtrip. +Negotiating the stream multiplexer takes one network roundtrip. This document defines a backwards-compatible optimization, which allows running the multiplexer negotiation during the cryptographic handshake, thereby reducing the latency of connection establishment by one roundtrip. @@ -88,7 +88,7 @@ For the purpose of multiplexer negotiation, the protocol IDs of the stream multiplexers are sent, followed by "libp2p". An example list: - ["/yamux/1.0.0", "/mplex/6.7.0", "libp2p"] + [ "/yamux", "/mplex", "libp2p" ] The multiplexer list is ordered by the client's preference, with the most preferred multiplexer at the beginning. The server SHOULD pick the first protocol from the @@ -106,39 +106,34 @@ early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. The second message carries early data in the form of a list of multiplexers supported by the responder, ordered by preference. The initiator sends its -supported multiplexer list in the third message of the handshake process. +supported multiplexer list in the third message of the handshake process. It +MAY choose a single multiplexer from the responder's list and only send that +value. -For security reasons the early data SHALL not be processed until the Noise -handshake is finished. After the Noise handshake process is fully done, the -initiator and responder will both process the received early data and select the -multiplexer to be used. They both iterate through the responder's preferred -multiplexer list in order, and if the multiplexer is also supported by the -initiator, that multiplexer is selected. If no mutually supported multiplexer is -found, the multiplexer negotiation process MUST fall back to multistream --selection protocol. +The multiplexer to use is determined by picking the first item from the +initiator's list that both parties support. Example: Noise handshake between peers that have a mutually supported multiplexer. - Initiator supports: ["/yamux/1.0.0", "/mplex/6.7.0"] - Responder supports: ["/mplex/6.7.0", "/yamux/1.0.0"] + Initiator supports: [ "/yamux", "/mplex" ] + Responder supports: [ "/mplex", "/yamux" ] XX: -> e - <- e, ee, s, es, ["/mplex/6.7.0", "/yamux/1.0.0"] - -> s, se, ["/yamux/1.0.0", "/mplex/6.7.0"] + <- e, ee, s, es, [ "/mplex", "/yamux" ] + -> s, se, [ "/yamux", "/mplex" ] - After handshake is done, both parties can arrive on the same conclusion - and select "/mplex/6.7.0" as the multiplexer to use. + Negotiated: "/yamux" Example: Noise handshake between peers that don't have mutually supported multiplexers. - Responder supports: ["/mplex/6.7.0"] - Initiator supports: ["yamux/1.0.0"] + Responder supports: [ "/mplex" ] + Initiator supports: [ "yamux" ] XX: -> e - <- e, ee, s, es, ["/mplex/6.7.0"] - -> s, se, ["yamux/1.0.0"] + <- e, ee, s, es, [ "/mplex" ] + -> s, se, [ "yamux" ] After handshaking is done, early data processing will find no mutually supported multiplexer, and falls back to multistream-selection protocol. From eafbffcffccf2ff742721bdd551377273156551d Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 11:03:21 +1300 Subject: [PATCH 41/50] rename document, link to it from connections README --- connections/README.md | 6 ++++++ ...sel-in-sec-handshake.md => inlined-muxer-negotiation.md} | 0 2 files changed, 6 insertions(+) rename connections/{muxer-sel-in-sec-handshake.md => inlined-muxer-negotiation.md} (100%) diff --git a/connections/README.md b/connections/README.md index 1d51b498f..047a02f22 100644 --- a/connections/README.md +++ b/connections/README.md @@ -234,6 +234,11 @@ Note: In the case where both peers initially act as initiators, e.g. during NAT hole punching, tie-breaking is done via the [multistream-select simultaneous open protocol extension][simopen]. +### Inlining Muxer Negotiation + +If both peers support it, it's possible to shortcut the muxer selection by moving +it into the security handshake. Details are specified in [inlined-muxer-negotiation]. + ## Opening New Streams Over a Connection @@ -409,3 +414,4 @@ updated to incorporate the changes. [simopen]: ./simopen.md [resource-manager-issue]: https://github.com/libp2p/go-libp2p/issues/635 [hole-punching]: ./hole-punching.md +[inlined-muxer-selection]: ./inlined-muxer-negotiation.md diff --git a/connections/muxer-sel-in-sec-handshake.md b/connections/inlined-muxer-negotiation.md similarity index 100% rename from connections/muxer-sel-in-sec-handshake.md rename to connections/inlined-muxer-negotiation.md From 1e52c1ee7d3430d36921322463bf590d943f781c Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 11:05:15 +1300 Subject: [PATCH 42/50] remove section describing current muxer selection --- connections/inlined-muxer-negotiation.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index 7fd0ab61f..9f3e6f2a0 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -3,7 +3,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|---------------|--------|-----------------| -| 1A | Working Draft | Active | r1, 2022-09-07 | +| 1A | Working Draft | Active | r1, 2022-12-07 | Authors: [@julian88110], [@marten-seemann] @@ -44,21 +44,6 @@ connection establishment by one roundtrip. ## Design -### Current connection upgrade process - -The current connection upgrade process is described in detail in [connections]. -As shown in this [sequence-chart], after a network connection is established, -the following will happen to upgrade the connection to a secured and stream- -multiplexed connection. - -1. The multistream-selection protocol is run over the connection to select the -security protocol to be used. -2. The selected security protocol performs handshaking and establishes a secure -tunnel -3. The multistream-selection protocol then will run again for stream multiplexer -negotiation. -4. The selected stream multiplexer is then used on the secured connection. - ### Improved multiplexer negotiation The security protocol's ability of supporting higher level abstract protocol From fe88ccfb258275f407496b85968333b1c75d15d9 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 11:08:20 +1300 Subject: [PATCH 43/50] remove repetitive section introducing muxer selection --- connections/inlined-muxer-negotiation.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index 9f3e6f2a0..9084f9bbb 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -44,21 +44,6 @@ connection establishment by one roundtrip. ## Design -### Improved multiplexer negotiation - -The security protocol's ability of supporting higher level abstract protocol -negotiation (for example, TLS's support of ALPN, and Noise's support of Early -Data) makes it possible to collapse the step 2 and step 3 in the previous -section into one step. Multiplexer negotiation can be performed as part of the -security protocol handshake, thus there is no need to perform another -multistream-selection negotiation for multiplexer negotiation. - -If the client and server agree upon the common multiplexer to be used, then the -result of the multiplexer negotiation is used as the selected stream -multiplexer. If no agreement is reached upon by the client and server then the -connection upgrade process MUST fall back to the multistream-selection protocol -to negotiate the multiplexer. - ### Multiplexer negotiation over TLS When the security protocol selected by the upgrader is TLS, the [ALPN] From da63658f3b302f5f96746ae67980c3b6cee62ae6 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 11:12:49 +1300 Subject: [PATCH 44/50] improve TLS section --- connections/inlined-muxer-negotiation.md | 27 ++++++++++++------------ 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index 9084f9bbb..db42dde8a 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -44,10 +44,9 @@ connection establishment by one roundtrip. ## Design -### Multiplexer negotiation over TLS +### Multiplexer Negotiation over TLS -When the security protocol selected by the upgrader is TLS, the [ALPN] -extension of TLS handshake is used to select the multiplexer. +When using TLS, the [ALPN] extension is used to negotiate the multiplexer. The ALPN TLS extension allows the client to send a list of supported application protocols as part of the TLS ClientHello message. The server chooses @@ -55,19 +54,21 @@ a protocol and sends the selected protocol as part of the TLS ServerHello message. For the purpose of multiplexer negotiation, the protocol IDs of the stream -multiplexers are sent, followed by "libp2p". - An example list: +multiplexers are sent, followed by "libp2p". The multiplexer list is ordered by +the client's preference, with the most preferred multiplexer at the beginning. +The server SHOULD respect the client's preference and pick the first protocol +from the list that it supports. - [ "/yamux", "/mplex", "libp2p" ] - -The multiplexer list is ordered by the client's preference, with the most preferred -multiplexer at the beginning. The server SHOULD pick the first protocol from the -list that it supports. +Example for a node supporting both yamux and mplex, with a preference for yamux: +```json +[ "/yamux/1.0.0", "/mplex/6.7.0", "libp2p" ] +``` The "libp2p" protocol code MUST always be the last item in the multiplexer list. -According to [tls], nodes that don't implement the optimization described in this document -use "libp2p" for their ALPN. If "libp2p" is the result of the ALPN process, nodes MUST use -multistream negotiation of the stream multiplexer as described in [connections]. +According to [tls], nodes that don't implement the optimization described in +this document use "libp2p" for their ALPN. If "libp2p" is the result of the +ALPN process, nodes MUST use multistream negotiation of the stream multiplexer +as described in [connections]. ### Multiplexer negotiation over Noise From 1306199cdc89820de1044e760f54d87fe34b9178 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 11:21:18 +1300 Subject: [PATCH 45/50] condense Noise section --- connections/inlined-muxer-negotiation.md | 47 +++++++++--------------- 1 file changed, 17 insertions(+), 30 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index db42dde8a..95d8170a8 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -70,49 +70,36 @@ this document use "libp2p" for their ALPN. If "libp2p" is the result of the ALPN process, nodes MUST use multistream negotiation of the stream multiplexer as described in [connections]. -### Multiplexer negotiation over Noise +### Multiplexer Negotiation over Noise -The libp2p Noise Specification allows the Noise handshake messages to carry +The libp2p Noise Specification allows Noise handshake messages to carry early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. The second message carries early data in the form of a list of multiplexers -supported by the responder, ordered by preference. The initiator sends its -supported multiplexer list in the third message of the handshake process. It +supported by the responder.The initiator sends its supported multiplexer list +in the third message of the handshake process, ordered by its preference. It MAY choose a single multiplexer from the responder's list and only send that value. The multiplexer to use is determined by picking the first item from the initiator's list that both parties support. -Example: Noise handshake between peers that have a mutually supported -multiplexer. - Initiator supports: [ "/yamux", "/mplex" ] - Responder supports: [ "/mplex", "/yamux" ] +Example: Noise handshake two clients that both support mplex and yamux. The +client prefers yamux, whereas the server prefers mplex. - XX: - -> e - <- e, ee, s, es, [ "/mplex", "/yamux" ] - -> s, se, [ "/yamux", "/mplex" ] - - Negotiated: "/yamux" - -Example: Noise handshake between peers that don't have mutually supported -multiplexers. - Responder supports: [ "/mplex" ] - Initiator supports: [ "yamux" ] +``` +XX: +-> e +<- e, ee, s, es, [ "/mplex/6.7.0", "/yamux/1.0.0" ] +-> s, se, [ "/yamux/1.0.0", "/mplex/6.7.0" ] +``` - XX: - -> e - <- e, ee, s, es, [ "/mplex" ] - -> s, se, [ "yamux" ] - - After handshaking is done, early data processing will find no mutually - supported multiplexer, and falls back to multistream-selection protocol. +The result of this negotiation is "/mplex/6.7.0". -The multiplexer selection logic SHOULD run after the Noise handshake has -finished mutual authentication of the peers to enhance security. +If there is no overlap between the multiplexers support by client and server, +the handshake MUST fail. -The format of the early data is specified in [Noise-handshake-payload] +The format of the early data is specified in [Noise-handshake-payload]. ## Privacy @@ -131,7 +118,7 @@ list of multiplexers. ## Alternative options considered Instead of ALPN for multiplexer selection to reduce RTT, other options such as -TLS extension and X.509 extension are considered. The pros and cons are explored +TLS extension and X.509 extension were considered. The pros and cons are explored and the discussion details can be found at [#454]. From bb070b218db209d6737b44e4237a4dae87b5d509 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Tue, 6 Dec 2022 15:15:55 -0800 Subject: [PATCH 46/50] Apply suggestions from code review Co-authored-by: Prithvi Shahi <50885601+p-shahi@users.noreply.github.com> --- connections/inlined-muxer-negotiation.md | 46 +++++++++++------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index 95d8170a8..9d3c48443 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -19,18 +19,14 @@ and spec status. [lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md -## Table of Contents - -- [multiplexer negotiation in security handshake](#multiplexer-negotiation-in-security-handshake) - - [Table of Contents](#table-of-contents) - - [Overview](#overview) - - [Design](#design) - - [Current connection upgrade process](#current-connection-upgrade-process) - - [Improved multiplexer negotiation](#improved-multiplexer-negotiation) - - [Multiplexer negotiation over TLS](#multiplexer-negotiation-over-tls) - - [Multiplexer negotiation over Noise](#multiplexer-negotiation-over-noise) - - [Security](#security) - - [Alternative options considered](#alternative-options-considered) +## Table of Contents + +- [Overview](#overview) +- [Design](#design) + - [Multiplexer Negotiation over TLS](#multiplexer-negotiation-over-tls) + - [Multiplexer Negotiation over Noise](#multiplexer-negotiation-over-noise) +- [Privacy](#privacy) +- [Alternative options considered](#alternative-options-considered) ## Overview @@ -54,7 +50,7 @@ a protocol and sends the selected protocol as part of the TLS ServerHello message. For the purpose of multiplexer negotiation, the protocol IDs of the stream -multiplexers are sent, followed by "libp2p". The multiplexer list is ordered by +multiplexers are sent, followed by the `"libp2p"` protocol code. The multiplexer list is ordered by the client's preference, with the most preferred multiplexer at the beginning. The server SHOULD respect the client's preference and pick the first protocol from the list that it supports. @@ -64,9 +60,9 @@ Example for a node supporting both yamux and mplex, with a preference for yamux: [ "/yamux/1.0.0", "/mplex/6.7.0", "libp2p" ] ``` -The "libp2p" protocol code MUST always be the last item in the multiplexer list. -According to [tls], nodes that don't implement the optimization described in -this document use "libp2p" for their ALPN. If "libp2p" is the result of the +The `"libp2p"` protocol code MUST always be the last item in the multiplexer list. +According to [TLS], nodes that don't implement the optimization described in +this document use `"libp2p"` for their ALPN. If `"libp2p"` is the result of the ALPN process, nodes MUST use multistream negotiation of the stream multiplexer as described in [connections]. @@ -76,7 +72,7 @@ The libp2p Noise Specification allows Noise handshake messages to carry early data. [Noise-Early-Data] is carried in the second and third message of the XX handshake pattern as illustrated in the following message sequence chart. The second message carries early data in the form of a list of multiplexers -supported by the responder.The initiator sends its supported multiplexer list +supported by the responder. The initiator sends its supported multiplexer list in the third message of the handshake process, ordered by its preference. It MAY choose a single multiplexer from the responder's list and only send that value. @@ -84,7 +80,7 @@ value. The multiplexer to use is determined by picking the first item from the initiator's list that both parties support. -Example: Noise handshake two clients that both support mplex and yamux. The +Example: Noise handshake between two clients that both support mplex and yamux. The client prefers yamux, whereas the server prefers mplex. ``` @@ -94,7 +90,7 @@ XX: -> s, se, [ "/yamux/1.0.0", "/mplex/6.7.0" ] ``` -The result of this negotiation is "/mplex/6.7.0". +The result of this negotiation is `"/mplex/6.7.0"`. If there is no overlap between the multiplexers support by client and server, the handshake MUST fail. @@ -105,12 +101,12 @@ The format of the early data is specified in [Noise-handshake-payload]. ## Privacy The list of multiplexers carried in the TLS ALPN extension field is part of the -ClientHello message which is not encrypted. Using this optimiziation therefore +unencrypted ClientHello message. Therefore, using this optimization exposes the list of supported multiplexers to an on-path observer. This leak can be considered insignificant, since a libp2p node reveals its list of supported multiplexers to any node that connects to it. -The NoiseExtensions sent in the Noise handshake is sent after the peers have +However, the NoiseExtensions in the Noise handshake are sent after the peers have established a shared key, so an on-path observer won't be able to obtain the list of multiplexers. @@ -122,14 +118,12 @@ TLS extension and X.509 extension were considered. The pros and cons are explore and the discussion details can be found at [#454]. - -[#426]: https://github.com/libp2p/specs/issues/426 +[TLS]: https://github.com/libp2p/specs/blob/master/tls/tls.md [connections]: https://github.com/libp2p/specs/tree/master/connections -[sequence-chart]: https://github.com/libp2p/specs/tree/master/connections#upgrading-connections [ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 -[Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload +[Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#libp2p-data-in-handshake-messages [ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ [handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload [#454]: https://github.com/libp2p/specs/issues/454 -[Noise-handshake-payload]: https://github.com/libp2p/specs/blob/b0818fa956f9940a7cdee18198e0daf1645d8276/noise/README.md#libp2p-data-in-handshake-messages +[Noise-handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload From d90a15e53725453df42e000b5b73a0811b2380bb Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Tue, 6 Dec 2022 15:16:17 -0800 Subject: [PATCH 47/50] Apply suggestions from code review Co-authored-by: Prithvi Shahi <50885601+p-shahi@users.noreply.github.com> --- connections/inlined-muxer-negotiation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index 9d3c48443..bb9d66854 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -1,4 +1,4 @@ -# Stream multiplexer negotiation in security handshake +# Stream multiplexer negotiation in security handshake | Lifecycle Stage | Maturity | Status | Latest Revision | From 447be1f5ce261f1ff07900efbf158abf59e3cad6 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Tue, 6 Dec 2022 15:16:29 -0800 Subject: [PATCH 48/50] Apply suggestions from code review Co-authored-by: Prithvi Shahi <50885601+p-shahi@users.noreply.github.com> --- connections/inlined-muxer-negotiation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index bb9d66854..c773a8af6 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -123,7 +123,6 @@ and the discussion details can be found at [#454]. [ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 [Noise-Early-Data]: https://github.com/libp2p/specs/tree/master/noise#libp2p-data-in-handshake-messages [ECH]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ -[handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload [#454]: https://github.com/libp2p/specs/issues/454 [Noise-handshake-payload]: https://github.com/libp2p/specs/tree/master/noise#the-libp2p-handshake-payload From c23af93da1d48097007e545291f133fe408e754c Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 7 Dec 2022 12:35:20 +1300 Subject: [PATCH 49/50] bump revisions --- connections/README.md | 2 +- noise/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/connections/README.md b/connections/README.md index 047a02f22..22338f622 100644 --- a/connections/README.md +++ b/connections/README.md @@ -2,7 +2,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|---------------|--------|-----------------| -| 1A | Working Draft | Active | r0, 2019-06-20 | +| 1A | Working Draft | Active | r1, 2022-12-07 | Authors: [@yusefnapora] diff --git a/noise/README.md b/noise/README.md index 3cb09d9ba..714c80a34 100644 --- a/noise/README.md +++ b/noise/README.md @@ -5,7 +5,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|----------------|--------|-----------------| -| 3A | Recommendation | Active | r4, 2022-09-22 | +| 3A | Recommendation | Active | r5, 2022-12-07 | Authors: [@yusefnapora] From 6fe4166fea0269dfc7208a240079f79f0fc0f6c9 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Sun, 11 Dec 2022 23:33:44 -0800 Subject: [PATCH 50/50] Apply suggestions from code review Co-authored-by: Elena Frank --- connections/inlined-muxer-negotiation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/connections/inlined-muxer-negotiation.md b/connections/inlined-muxer-negotiation.md index c773a8af6..a437dfce9 100644 --- a/connections/inlined-muxer-negotiation.md +++ b/connections/inlined-muxer-negotiation.md @@ -45,9 +45,9 @@ connection establishment by one roundtrip. When using TLS, the [ALPN] extension is used to negotiate the multiplexer. The ALPN TLS extension allows the client to send a list of supported application -protocols as part of the TLS ClientHello message. The server chooses +protocols as part of the TLS `ClientHello` message. The server chooses a protocol and sends the selected protocol as part of the TLS -ServerHello message. +`ServerHello` message. For the purpose of multiplexer negotiation, the protocol IDs of the stream multiplexers are sent, followed by the `"libp2p"` protocol code. The multiplexer list is ordered by @@ -63,7 +63,7 @@ Example for a node supporting both yamux and mplex, with a preference for yamux: The `"libp2p"` protocol code MUST always be the last item in the multiplexer list. According to [TLS], nodes that don't implement the optimization described in this document use `"libp2p"` for their ALPN. If `"libp2p"` is the result of the -ALPN process, nodes MUST use multistream negotiation of the stream multiplexer +ALPN process, nodes MUST use protocol negotiation of the stream multiplexer as described in [connections]. ### Multiplexer Negotiation over Noise