Archives/lnbook
2
0
Fork 0
mirror of https://github.com/lnbook/lnbook synced 2024-11-04 18:00:26 +00:00
Code Issues Projects Releases Wiki Activity

ch-10: fix ordering of HMAC steps, HMAC is computed over encrypted payload

Browse Source 
The outer HMAC for the final hop is computed over the encrypted payload. Instead, the inner HMAC is just blank for the final hop. In this commit, we switch the ordering to reflect this. The diagrams will need to be updated as well.
This commit is contained in:
Olaoluwa Osuntokun 2021-07-25 19:36:41 -07:00 committed by Andreas M. Antonopoulos
parent 351d45b669
commit e2d2bede3d
1 changed files with 9 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
10_onion_routing.asciidoc
View File

@ -422,23 +422,12 @@ Alice starts with an empty 1300 byte field, the fixed-length _onion payload_. Th
Random byte-stream generation uses the ChaCha20 algorithm, as a Cryptographic Secure Pseudo-Random Number Generator (CSPRNG). Such an algorithm will generate a deterministic, long non-repeating stream of seemingly random bytes from an initial seed. The details are specified in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#pseudo-random-byte-stream[BOLT #4 - Onion Routing - Pseudo Random Byte Stream].
====
This is shown in <<onion_payload_filler>>:
[[onion_payload_filler]]
.Filling the onion payload with a random byte-stream
image::images/onion_payload_filler.png[]
Next, Alice calculates a Hash-based Message Authentication Code (HMAC) for Dina's payload, which uses the _mu_ key as it's initialization key. This is shown in <<dina_hop_payload_hmac>>:
[[dina_hop_payload_hmac]]
.Adding an HMAC integrity checksum to Dina's hop payload
image::images/dina_hop_payload_hmac.png[]
The HMAC acts as a secure checksum and helps Dina verify the integrity of the hop payload. The 32-byte HMAC is appended to Dina's hop payload.
Alice will now insert Dina's hop payload into the left side of the 1300 byte array, shifting the filler to the right and discarding anything that overflows. This is visualized in <<onion_add_dina>>:
[[onion_add_dina]]
@ -449,7 +438,7 @@ Another way to look at this is that Alice measures the length of Dina's hop payl
Next row down we see the result: the 1300 byte onion payload contains Dina's hop payload and then the filler byte-stream filling up the rest of the space.
Finally, Alice obfuscates the entire onion payload so that *only Dina* can read it.
Next, Alice obfuscates the entire onion payload so that *only Dina* can read it.
To do this, Alice generates a byte-stream using the +rho+ key (which Dina also knows). Alice uses a bitwise exclusive-or (XOR) between the bits of the onion payload and the byte-stream created from +rho+. The result appears like a random (or encrypted) byte stream of 1300 bytes length. This step is shown in <<onion_obfuscate_dina>>:
@ -466,6 +455,14 @@ XOR is an _involutory_ function which means that if it is applied twice it undoe
Since only Alice and Dina have the +rho+ key (derived from Alice and Dina's shared secret), only they can do this. Effectively, this encrypts the onion payload for Dina's eyes only.
Finally, Alice calculates a Hash-based Message Authentication Code (HMAC) for Dina's payload, which uses the _mu_ key as it's initialization key. This is shown in <<dina_hop_payload_hmac>>:
[[dina_hop_payload_hmac]]
.Adding an HMAC integrity checksum to Dina's hop payload
image::images/dina_hop_payload_hmac.png[]
The HMAC acts as a secure checksum and helps Dina verify the integrity of the hop payload. The 32-byte HMAC is appended to Dina's hop payload.
Note that we compute the HMAC over the _encrypted_ data rather then over the plaintext data.
This is known as "encrypt-then-mac" and is the recommended way to use a MAC, as it provides both plaintext _and_ cihpertext integrity.
==== Wrapping Chan's hop payload
In <<chan_onion_wrapping>> we see the steps used to wrap Chan's hop payload in the onion. These are the same steps Alice used to wrap Dina's hop payload.