[noise] NoiseSocket API feedback

[Nemanja Mijailovic]

Hi all,

I've been implementing the NoiseSocket protocol in C# for the last several days. The library is not yet done (it will probably be in a week or so), but I think I have enough feedback on the spec.

It's fairly easy to follow and implement. First four sections are clear, but I think that the API section needs a bit more work.

1) Initialize

Current definition:
- INPUT: pattern, dh, cipher, hash
- OUTPUT: session object

It's strange that not all inputs are specified here. I would either mirror the definition of Initialize in HandshakeState from the Noise specification:
INPUT: handshake_pattern, initiator, prologue, s, e, rs, re

Or maybe just say something more abstract like:
INPUT: noise_protocol

I think that the OUTPUT is not necessary here, so I would just remove it—it's not clear what is the meaning of "session object", and it's not mentioned anywhere else in the specification (except in Reinitialize).

2) ReadHandshakeMessage

ReadHandshakeMessage takes handshake_message as a parameter. This may lead the implementer to believe that the parameter is a byte sequence that contains the whole message that the user has somehow obtained prior to the call. In practice, you will most likely pass the input stream as a parameter, and read the handshake_message from it (when I say stream, I mean something that you can read a sequence of one or more bytes from, like Go's io.Reader, or Java's InputStream). Maybe someting like this would be clearer:

ReadHandshakeMessage:

- INPUT: input_stream
- OUTPUT: message_body
- DESCRIPTION: Reads the handshake_message from the input_stream and returns the message_body.

If you think that the idea with streams makes sense, then all similar functions would be updated in the same fashion.

3) PeekHandshakeMessage

PeekHandshakeMessage will probably completely consume the negotiation data, so I would just rename it to ReadNegotiationData.

4) WriteEmptyHandshakeMessage

It does exactly the same thing as the WriteHandshakeMessage when the message_body is omitted, so I would just drop this one.

Nemanja

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://moderncrypto.org/mail-archive/noise/attachments/20180418/6640729a/attachment.html>