BOLT-8 Edits by shannona · Pull Request #311 · lightning/bolts

shannona · 2017-12-08T00:18:29Z

More clarity and copyediting. I also removed quite a few `s that didn't seem to match general usage for "code".

rustyrussell · 2017-12-08T01:16:07Z

+the responder. This provides a degree of identity hiding for the
+responder, as its public key is _never_ transmitted during the handshake. Instead,
+authentication is achieved implicitly via a series of Elliptic-Curve
+Diffie-Hellman (ECDH) operations followed by a MAC check.


The term "pre-message" is taken from the Noise spec, https://noiseprotocol.org/noise.html#handshake-patterns.

Changed back to "As a pre-message" (and it reads better now with the changes to the rest of the sentence).

rustyrussell · 2017-12-08T01:22:53Z

 The initiator should produce the given output when fed this input.
 The comments reflect internal state for debugging.
-
+```


Technically indentation serves the same purpose as triple-quote in markdown, but there's nothing wrong with both AFAICT.

rustyrussell

Nice, much more consistent with rest of spec formatting (@Roasbeef wrote this really early on when we were still shaking that stuff loose).

toadlyBroodle

Nice one :)

toadlyBroodle · 2017-12-08T04:39:09Z

-encryption keys (`ck` the chaining key and `k` the encryption key), and finally
-an `AEAD` payload with a zero length cipher text is sent.  As this payload is
-of length zero, only a `MAC` is sent across.  The mixing of `ECDH` outputs into
+steps. During each "act" of the handshake: some (possibly encrypted) keying


original comma was correct, as the first clause is a prepositional phrase, not a complete sentence

I prefer the clarity of leading off semi-colon separated lists with a colon, so I've changed the first clause into a sentence to allow this.

toadlyBroodle · 2017-12-08T04:42:12Z

+which act is being executed, with the result mixed into the current set of
+encryption keys (`ck` the chaining key and `k` the encryption key); and 
+an AEAD payload with a zero-length cipher text is sent. As this payload is
+length zero, only a MAC is sent across. The mixing of ECDH outputs into


...payload has no length, only...

Better sounding. Changed.

toadlyBroodle · 2017-12-08T04:48:23Z

   new ephemeral key with strong cryptographic randomness.

- * `s`: A party's **static public key** (`ls` for local, `rs` for remote)
+ * `s`: A party's **static public key** (`ls` for local, `rs` for remote).


stylesheet rule is to only use periods at end of list items if they are complete sentences, so original is consistent with stylesheet

Thanks; must have intended that for the previous item!

toadlyBroodle · 2017-12-08T04:55:10Z

-    * where `m[0]` is the _first_ byte of `m`, `m[1:33]` are the next `33`
-      bytes of `m` and `m[34:]` is the last 16 bytes of `m`
+  * Read _exactly_ 50 bytes from the network buffer.
+  * Parse out the read message (`m`) into `v = m[0]`, `re = m[1:33]` and `c = m[34:]`.


...re = m[1:33], and...

Sent to Oxford.

toadlyBroodle · 2017-12-08T05:04:41Z

-
+       the responder
+     * The final encryption keys to be used for sending and
+       receiving messages for the duration of the session are generated.


the final...generated

It's a complete sentence, not in a requirements list, so it should be capitalized and have a period, yes?

Oops, sorry you're right.

Great! I was momentarily confused!

toadlyBroodle · 2017-12-08T05:05:10Z

-  * Read _exactly_ `66-bytes` from the network buffer.
-
-
+  * Read _exactly_ 66-bytes from the network buffer.


toadlyBroodle · 2017-12-08T05:06:22Z

-
+       the initiator
+     * The final encryption keys to be used for sending and
+       receiving messages for the duration of the session are generated


period is appropriate here

toadlyBroodle · 2017-12-08T05:12:25Z

+  * let `l = len(m)`
+    * where `len` obtains the length in bytes of the Lightning message
+  * Serialize `l` into 2 bytes encoded as a big-endian integer.
+  * Encrypt `l` using `ChaChaPoly-1305`, `sn`, and `sk`, to obtain `lc`


...1 (using...sk), to...

Changed three instances of this.

toadlyBroodle · 2017-12-08T05:14:57Z

-
-
-  * Decrypt `c` using `ChaCha20-Poly1305`, `rn`, and `rk` to obtain decrypted
+  * Decrypt `c` using `ChaCha20-Poly1305`, `rn`, and `rk`, to obtain decrypted


...obtain the decrypted

Changed three instances of this.

toadlyBroodle · 2017-12-08T05:15:56Z

-Changing keys regularly and forgetting the previous key is useful for
-preventing decryption of old messages in the case of later key leakage (ie.
+Changing keys regularly and forgetting previous keys is useful to
+prevent the decryption of old messages in the case of later key leakage (i.e.


...messages, in...

@rustyrussell

(1) addressed review items from @rustyrussell and @toadlyBroodle ; and (2) added table of contents courtesy of @bcongdon in #310

shannona · 2017-12-08T19:01:04Z

Responses to reviews now in place, as well as table of contents courtesy of @bcongdon in #310

@dimitris-t

Added fix for duplicate word courtesy of @dimitris-t in #306.

toadlyBroodle · 2017-12-08T19:40:47Z

   new ephemeral key with strong cryptographic randomness.

- * `s`: A party's **static public key** (`ls` for local, `rs` for remote).
+ * `s`: A party's **static public key** (`ls` for local, `rs` for remote)


...a party's...

Got it, thanks.

BOLT-8 Edits

913751e

More clarity and copyediting. I also removed quite a few `s that didn't seem to match general usage for "code".

rustyrussell approved these changes Dec 8, 2017

View reviewed changes

rustyrussell requested review from Roasbeef and toadlyBroodle December 8, 2017 01:24

toadlyBroodle reviewed Dec 8, 2017

View reviewed changes

Responses to BOLT-8 Reviews

65d7379

(1) addressed review items from @rustyrussell and @toadlyBroodle ; and (2) added table of contents courtesy of @bcongdon in #310

shannona mentioned this pull request Dec 8, 2017

BOLT 7,8,11: Add table-of-contents #310

Closed

Fix from #306

0b34aa3

Added fix for duplicate word courtesy of @dimitris-t in #306.

shannona mentioned this pull request Dec 8, 2017

Fixed typos #306

Closed

toadlyBroodle approved these changes Dec 8, 2017

View reviewed changes

Lower-cased an "a".

2f69bd7

rustyrussell merged commit 0d74fd7 into lightning:master Dec 10, 2017

		* Read _exactly_ `66-bytes` from the network buffer.


		* Read _exactly_ 66-bytes from the network buffer.



		* Decrypt `c` using `ChaCha20-Poly1305`, `rn`, and `rk` to obtain decrypted
		* Decrypt `c` using `ChaCha20-Poly1305`, `rn`, and `rk`, to obtain decrypted

Conversation

shannona commented Dec 8, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustyrussell left a comment

Choose a reason for hiding this comment

Uh oh!

toadlyBroodle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shannona commented Dec 8, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants