From 685ef18150799449c5aa825be66391ad4acd61ae Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Wed, 14 Sep 2022 20:00:42 +0300 Subject: [PATCH 1/5] noise: introduce an extension registry --- noise/README.md | 55 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 17 deletions(-) diff --git a/noise/README.md b/noise/README.md index c981b1423..e042ae4d7 100644 --- a/noise/README.md +++ b/noise/README.md @@ -5,7 +5,7 @@ | Lifecycle Stage | Maturity | Status | Latest Revision | |-----------------|----------------|--------|-----------------| -| 3A | Recommendation | Active | r3, 2022-09-20 | +| 3A | Recommendation | Active | r4, 2022-09-22 | Authors: [@yusefnapora] @@ -200,18 +200,16 @@ The Noise Protocol Framework caters for sending early data alongside handshake messages. We leverage this construct to transmit: 1. the libp2p identity key along with a signature, to authenticate each party to - the other. -2. arbitrary data private to the libp2p stack. This facility is not exposed to - userland. Examples of usage include streamlining muxer selection. - -These payloads MUST be inserted into the first message of the handshake pattern -**that guarantees secrecy**. In practice, this means that the initiator must not -send a payload in their first message. Instead, the initiator will send its -payload in message 3 (closing message), whereas the responder will send theirs -in message 2 (their only message). It should be stressed, that the second -message of the handshake pattern has forward secrecy, however the sender has not -authenticated the responder, so this payload might be sent to any party, -including an active attacker. + the other, and +2. extensions to the Noise handshake + +Note that when sending extensions with the first message of the handshake +pattern, the data is transmitted unencrypted. When sending the payload in +message 3 (closing message), for the initiator, and in message 2, for the +responder, the data will be send encrypted with forward secrecy. +It should be stressed, that while the second message of the handshake pattern +has forward secrecy, the sender has not yet authenticated the responder, +so this payload might be sent to any party, including an active attacker. When decrypted, the payload contains a serialized [protobuf][protobuf] `NoiseHandshakePayload` message with the following schema: @@ -219,10 +217,16 @@ When decrypted, the payload contains a serialized [protobuf][protobuf] ``` protobuf syntax = "proto2"; +message NoiseExtensions { + repeated bytes webtransport_certhashes = 1; + optional bytes webrtc_fingerprint = 2; + repeated string stream_muxers = 3; +} + message NoiseHandshakePayload { optional bytes identity_key = 1; optional bytes identity_sig = 2; - optional bytes data = 3; + optional NoiseExtensions extensions = 4; } ``` @@ -235,9 +239,8 @@ spec][peer-id-spec-signing-rules]. The data to be signed is the UTF-8 string `noise-libp2p-static-key:`, followed by the Noise static public key, encoded according to the rules defined in [section 5 of RFC 7748][rfc-7748-sec-5]. -The `data` field contains the "early data" provided to the Noise module when -initiating the handshake, if any. The structure of this data is opaque to -noise-libp2p and is defined in the connection establishment specs. +The `extensions` field contains Noise extensions and is described in +[Noise Extensions](#noise-extensions). Upon receiving the handshake payload, peers MUST decode the public key from the `identity_key` field into a usable form. The key MUST then be used to validate @@ -283,6 +286,24 @@ internal libp2p data. The XX handshake MUST be supported by noise-libp2p implementations. +### Noise Extensions + +Since the Noise handshake pattern itself doesn't define any extensibility +mechanism, this specification defines an extension registry, modeled after +[RFC 6066](https://www.rfc-editor.org/rfc/rfc6066) (for TLS) and +[RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000#section-19.21) +(for QUIC). + +This spec currently defines 3 extension code points for the `NoiseExtensions` +protobuf. Note that this document only defines the code point, and leaves +it up to the protocol using that code point to define semantics associated +with that code point. + +Code points above 1024 MAY be used for experimentation. Code points up to +this value MUST be registered in this document before deployment. + + + ## Cryptographic Primitives The Noise framework allows protocol designers to choose from a small set of From 7a517afa24ebe4a3516e17cd1bcafdcfd7fa519c Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Thu, 15 Sep 2022 21:13:11 +0300 Subject: [PATCH 2/5] noise: remove WebRTC and stream muxer from NoiseExtensions --- noise/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/noise/README.md b/noise/README.md index e042ae4d7..dcbd186ad 100644 --- a/noise/README.md +++ b/noise/README.md @@ -219,8 +219,6 @@ syntax = "proto2"; message NoiseExtensions { repeated bytes webtransport_certhashes = 1; - optional bytes webrtc_fingerprint = 2; - repeated string stream_muxers = 3; } message NoiseHandshakePayload { From 215419c727be7d93c25e7b7cf5a96635a41195dc Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 16 Sep 2022 09:37:35 +0300 Subject: [PATCH 3/5] don't specify how many Noise extensions there are --- noise/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/noise/README.md b/noise/README.md index dcbd186ad..fa96e866d 100644 --- a/noise/README.md +++ b/noise/README.md @@ -292,10 +292,9 @@ mechanism, this specification defines an extension registry, modeled after [RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000#section-19.21) (for QUIC). -This spec currently defines 3 extension code points for the `NoiseExtensions` -protobuf. Note that this document only defines the code point, and leaves -it up to the protocol using that code point to define semantics associated -with that code point. +Note that this document only defines the `NoiseExtensions` code points, and +leaves it up to the protocol using that code point to define semantics +associated with these code point. Code points above 1024 MAY be used for experimentation. Code points up to this value MUST be registered in this document before deployment. From 0991510c9eee728b3127322329697f3fa5a5ba14 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 16 Sep 2022 09:41:52 +0300 Subject: [PATCH 4/5] improve description of extensions --- noise/README.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/noise/README.md b/noise/README.md index fa96e866d..e0285556b 100644 --- a/noise/README.md +++ b/noise/README.md @@ -200,16 +200,17 @@ The Noise Protocol Framework caters for sending early data alongside handshake messages. We leverage this construct to transmit: 1. the libp2p identity key along with a signature, to authenticate each party to - the other, and -2. extensions to the Noise handshake - -Note that when sending extensions with the first message of the handshake -pattern, the data is transmitted unencrypted. When sending the payload in -message 3 (closing message), for the initiator, and in message 2, for the -responder, the data will be send encrypted with forward secrecy. -It should be stressed, that while the second message of the handshake pattern -has forward secrecy, the sender has not yet authenticated the responder, -so this payload might be sent to any party, including an active attacker. + the other. +2. extensions used by the libp2p stack. + +The extensions are inserted into the first message of the handshake pattern +**that guarantees secrecy**. Specifically, this means that the initiator MUST NOT +send extensions in their first message. +The initiator sends its extensions in message 3 (closing message), and the +responder sends theirs in message 2 (their only message). It should be stressed, +that while the second message of the handshake pattern has forward secrecy, +the sender has not authenticated the responder yet, so this payload might be +sent to any party, including an active attacker. When decrypted, the payload contains a serialized [protobuf][protobuf] `NoiseHandshakePayload` message with the following schema: From b0818fa956f9940a7cdee18198e0daf1645d8276 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Thu, 22 Sep 2022 22:54:23 +0300 Subject: [PATCH 5/5] noise: add Changelog --- noise/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/noise/README.md b/noise/README.md index e0285556b..7648b06d1 100644 --- a/noise/README.md +++ b/noise/README.md @@ -452,6 +452,14 @@ unsupported types like RSA. - Removed Noise Pipes and related handshake patterns - Removed padding within encrypted payloads +### r3 - 2022-09-20 + +- Change Protobuf definition to proto2 (due to the layout of the protobuf used, this is backwards-compatible change) + +### r4 - 2022-09-22 + +- Add Noise extension registry + [peer-id-spec]: ../peer-ids/peer-ids.md [peer-id-spec-signing-rules]: ../peer-ids/peer-ids.md#how-keys-are-encoded-and-messages-signed