[noise] Transport protocol spec finalizing

[Trevor Perrin]

On Wed, Jul 19, 2017 at 5:59 PM, Alexey Ermishkin <scratch.net at gmail.com> wrote:
> I've added some fixes, though not all of them. Same url.

https://github.com/noisesocket/spec/blob/master/output/noisesocket.pdf

At some point we can discuss linking this from the webpage or something.

The technical details look good.

I think this is still a difficult read for someone who doesn't already
understand the Noise spec.

Maybe there needs to be more Overview of what a Noise protocol is, and
the rationale for negotiation_data and prologue / transcript hashing.
Explaining all this in a simple way isn't easy.  Perhaps diagrams and
more examples would help.


Editorial:

Abstract: "[+and] back-end applications"

Overview:
 - "Usually [2] or [3] messages"
 - Fix formatting for "**negotiation_data**"
 - Not sure you need the sentence about "Usage of negotiation_data
without making it a part of the handshake" in this Overview, could be
deleted or moved to a Security Considerations section at the end.
 - This description is a step in the right direction, but it's still
somewhat confusing.  For example, you say a handshake packet contains
an optional field (negotiation_data) which is not part of the
handshake message.  I know what you're saying, but I think most
readers will have trouble with this.

2.2.
 - Probably don't bold entire sentence "Padding contents are abitrary...".

2.3.
 - I wouldn't mention the MixHash() option, since this isn't part of
Noise, and people reading this spec might not know what MixHash()
does.


5. API
 - The "Common logic" for padded_len is confusing and dense, should
probably be simplified.
 - I wouldn't use the term "cleartext_body", since only the initial
payload is technically cleartext.

6.
 - Probably not a good idea to reference Noise-C for constants, I'm
not sure Rhys intended this to be a permanent number registry.
 - It might be worthwhile to give a fully-worked-out and
self-contained Noise_XX example, i.e. just list out all the HMAC and
AEAD steps, so someone could implement that directly without the Noise
spec.


Trevor