diff --git a/noise/README.md b/noise/README.md index 4f1cb802c..a1350b8f6 100644 --- a/noise/README.md +++ b/noise/README.md @@ -210,16 +210,18 @@ 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. 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. When decrypted, the payload contains a serialized [protobuf][protobuf] `NoiseHandshakePayload` message with the following schema: