Clean-up nits

This commit doesn't change the logic at all, it simply: - removes `realm` from onion test vector - cleans-up markdown formatting and indents - fixes typos and missing parenthesis - consistently uses `_` instead of `-` for field names - fixes math formatting (including changes from lightning#1169 and lightning#1158)
rustyrussell · Jul 17, 2024 · dd27d4d · dd27d4d
1 parent 5193cbb
commit dd27d4d
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 58 deletions.
diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -2130,14 +2130,14 @@ A node:
     - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or
 `update_fail_malformed_htlc`.
   - When failing an incoming HTLC:
-    - If `current_path_key_point` is set in the onion payload and it is not the
+    - If `current_path_key` is set in the onion payload and it is not the
       final node:
       - MUST send an `update_fail_htlc` error using the `invalid_onion_blinding`
         failure code for any local or downstream errors.
       - SHOULD use the `sha256_of_onion` of the onion it received.
       - MAY use an all zero `sha256_of_onion`.
       - SHOULD add a random delay before sending `update_fail_htlc`.
-    - If `path_key_point` is set in the incoming `update_add_htlc`:
+    - If `path_key` is set in the incoming `update_add_htlc`:
       - MUST send an `update_fail_malformed_htlc` error using the
         `invalid_onion_blinding` failure code for any local or downstream errors.
       - SHOULD use the `sha256_of_onion` of the onion it received.

diff --git a/04-onion-routing.md b/04-onion-routing.md
@@ -321,7 +321,7 @@ The reader:
       - MUST return an error if incoming `cltv_expiry` < `outgoing_cltv_value`.
       - MUST return an error if incoming `cltv_expiry` < `current_block_height` + `min_final_cltv_expiry_delta`.
   - Otherwise (it is not part of a blinded route):
-    - MUST return an error if `path_key` is set in the incoming `update_add_htlc` or `current_pass` is present.
+    - MUST return an error if `path_key` is set in the incoming `update_add_htlc` or `current_path_key` is present.
     - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present.
     - if it is not the final node:
       - MUST return an error if:
@@ -495,20 +495,20 @@ may contain the following TLV fields:
 A recipient $`N_r`$ creating a blinded route $`N_0 \rightarrow N_1 \rightarrow ... \rightarrow N_r`$ to itself:
 
 - MUST create a blinded node ID $`B_i`$ for each node using the following algorithm:
-  - $`e_0 /leftarrow {0;1}^256`$ ($`e_0`$ SHOULD be obtained via CSPRG)
+  - $`e_0 \leftarrow \{0;1\}^{256}`$ ($`e_0`$ SHOULD be obtained via CSPRNG)
   - $`E_0 = e_0 \cdot G`$
   - For every node in the route:
     - let $`N_i = k_i * G`$ be the `node_id` ($`k_i`$ is $`N_i`$'s private key)
-    - $`ss_i = SHA256(e_i * N_i) = SHA256(k_i * E_i)$` (ECDH shared secret known only by $`N_r`$ and $`N_i`$)
+    - $`ss_i = SHA256(e_i * N_i) = SHA256(k_i * E_i)`$ (ECDH shared secret known only by $`N_r`$ and $`N_i`$)
     - $`B_i = HMAC256(\text{"blinded\_node\_id"}, ss_i) * N_i`$ (blinded `node_id` for $`N_i`$, private key known only by $`N_i`$)
     - $`rho_i = HMAC256(\text{"rho"}, ss_i)`$ (key used to encrypt the payload for $`N_i`$ by $`N_r`$)
     - $`e_{i+1} = SHA256(E_i || ss_i) * e_i`$ (ephemeral private path key, only known by $`N_r`$)
     - $`E_{i+1} = SHA256(E_i || ss_i) * E_i`$ (`path_key`. NB: $`N_i`$ MUST NOT learn $`e_i`$)
 - MAY replace $`E_{i+1}`$ with a different value, but if it does:
-  - MUST set `encrypted_data_tlv[i].next_path_key_override` to `$E_{i+1}$`
+  - MUST set `encrypted_data_tlv[i].next_path_key_override` to $`E_{i+1}`$
 - MAY store private data in `encrypted_data_tlv[r].path_id` to verify that the route is used in the right context and was created by them
 - SHOULD add padding data to ensure all `encrypted_data_tlv[i]` have the same length
-- MUST encrypt each `encrypted_data_tlv[i]` with ChaCha20-Poly1305 using the corresponding `rho_i` key and an all-zero nonce to produce `encrypted_recipient_data[i]`
+- MUST encrypt each `encrypted_data_tlv[i]` with ChaCha20-Poly1305 using the corresponding $`rho_i`$ key and an all-zero nonce to produce `encrypted_recipient_data[i]`
 - MUST communicate the blinded node IDs $`B_i`$ and `encrypted_recipient_data[i]` to the sender
 - MUST communicate the real node ID of the introduction point $`N_0`$ to the sender
 - MUST communicate the first `path_key` $`E_0`$ to the sender
@@ -518,7 +518,7 @@ A reader:
 - If it receives `path_key` ($`E_i`$) from the prior peer:
   - MUST use $`b_i`$ instead of its private key $`k_i`$ to decrypt the onion.
     Note that the node may instead tweak the onion ephemeral key with
-    $`HMAC256(\text{"blinded\_node\_id}", ss_i)`$ which achieves the same result.
+    $`HMAC256(\text{"blinded\_node\_id"}, ss_i)`$ which achieves the same result.
 - Otherwise:
   - MUST use $`k_i`$ to decrypt the onion, to extract `current_path_key` ($`E_i`$).
 - MUST compute:
@@ -557,7 +557,7 @@ keys of the nodes in the route with random public keys while letting senders
 choose what data they put in the onion for each hop. Blinded routes are also
 reusable in some cases (e.g. onion messages).
 
-Each node in the blinded route needs to receive `E_i` to be able to decrypt
+Each node in the blinded route needs to receive $`E_i`$ to be able to decrypt
 the onion and the `encrypted_data` payload. Protocols that use route blinding
 must specify how this value is propagated between nodes.
 
@@ -570,7 +570,7 @@ The final recipient must verify that the blinded route is used in the right
 context (e.g. for a specific payment) and was created by them. Otherwise a
 malicious sender could create different blinded routes to all the nodes that
 they suspect could be the real recipient and try them until one accepts the
-message. The recipient can protect against that by storing `E_r` and the
+message. The recipient can protect against that by storing $`E_r`$ and the
 context (e.g. a `payment_hash`), and verifying that they match when receiving
 the onion. Otherwise, to avoid additional storage cost, it can put some private
 context information in the `path_id` field (e.g. the `payment_preimage`) and
@@ -617,7 +617,7 @@ sent across.
 
 Nodes implementing non-strict forwarding are able to make real-time assessments
 of channel bandwidths with a particular peer, and use the channel that is
-locally-optimal. 
+locally-optimal.
 
 For example, if the channel specified by `short_channel_id` connecting A and B
 does not have enough bandwidth at forwarding time, then A is able use a
@@ -857,9 +857,10 @@ func NewOnionPacket(paymentPath []*btcec.PublicKey, sessionKey *btcec.PrivateKey
 
 # Onion Decryption
 
-There are two kinds of `onion_packet` we use: 
+There are two kinds of `onion_packet` we use:
+
 1. `onion_routing_packet` in `update_add_htlc` for payments, which contains a `payload` TLV (see [Adding an HTLC](02-peer-protocol.md#adding-an-htlc-update_add_htlc))
-2. `onion_message_packet` on `onion_message` for messages, which contains a `onionmsg_tlv` TLV (see [Onion Messages](#onion-messages)
+2. `onion_message_packet` in `onion_message` for messages, which contains an `onionmsg_tlv` TLV (see [Onion Messages](#onion-messages))
 
 Those sections specify the `associated_data` to use, the `path_key` (if any), the extracted payload format and handling (including how to determine the next peer, if any), and how to handle errors.  The processing itself is identical.
 
@@ -871,26 +872,26 @@ A reader:
   - if `public_key` is not a valid pubkey:
     - MUST abort processing the packet and fail.
   - if the onion is for a payment:
-  - if `hmac` has previously been received:
-    - if the preimage is known:
-      - MAY immediately redeem the HTLC using the preimage.
-    - otherwise:
-      - MUST abort processing the packet and fail.
+    - if `hmac` has previously been received:
+      - if the preimage is known:
+        - MAY immediately redeem the HTLC using the preimage.
+      - otherwise:
+        - MUST abort processing the packet and fail.
   - if `path_key` is specified:
-    - Calculate the `blinding_ss` as ECDH(`path_key`, `node-privkey`)
+    - Calculate the `blinding_ss` as ECDH(`path_key`, `node_privkey`).
     - Either:
-      - Tweak `public_key` by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$
+      - Tweak `public_key` by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$.
     - or (equivalently):
-      - Tweak its own `node-privkey` below by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$
- - Derive the shared secret `ss` as ECDH(`public_key`, `node-privkey`) (see [Shared Secret](#shared-secret))
+      - Tweak its own `node_privkey` below by multiplying by $`HMAC256(\text{"blinded\_node\_id"}, blinding\_ss)`$.
+  - Derive the shared secret `ss` as ECDH(`public_key`, `node_privkey`) (see [Shared Secret](#shared-secret)).
   - Derive `mu` as $`HMAC256(\text{"mu"}, ss)`$ (see [Key Generation](#key-generation)).
-  - Derive the HMAC as $`HMAC256(mu, hop_payloads || associated_data)`$
+  - Derive the HMAC as $`HMAC256(mu, hop\_payloads || associated\_data)`$.
   - MUST use a constant time comparison of the computed HMAC and `hmac`.
   - If the computed HMAC and `hmac` differ:
     - MUST abort processing the packet and fail.
   - Derive `rho` as $`HMAC256(\text{"rho"}, ss)`$ (see [Key Generation](#key-generation)).
   - Derive `bytestream` of twice the length of `hop_payloads` using `rho` (see [Pseudo Random Byte Stream](pseudo-random-byte-stream)).
-  - Set `unwrapped_payloads` to the XOR of `hop_payloads` and `bytestream`
+  - Set `unwrapped_payloads` to the XOR of `hop_payloads` and `bytestream`.
   - Remove a `bigsize` from the front of `unwrapped_payloads` as `payload_length`.  If that is malformed:
     - MUST abort processing the packet and fail.
   - If the `payload_length` is less than two:
@@ -904,22 +905,20 @@ A reader:
   - If `unwrapped_payloads` is smaller than `hop_payloads`:
     - MUST abort processing the packet and fail.
   - If `next_hmac` is not all-zero (not the final node):
-    - Derive `blinding_tweak` as $`SHA256(public_key || ss)`$ (see [Blinding Ephemeral Onion Keys](#blinding-ephemeral-onion-keys))
+    - Derive `blinding_tweak` as $`SHA256(public\_key || ss)`$ (see [Blinding Ephemeral Onion Keys](#blinding-ephemeral-onion-keys)).
     - SHOULD forward an onion to the next peer with:
-      - `version` set to 0
-      - `public_key` set to the incoming `public_key` multiplied by `blinding_tweak`
-      - `hop_payloads` set to the `unwrapped_payloads`, truncated to the incoming `hop_payloads` size
-      - `hmac` set to `next_hmac`
+      - `version` set to 0.
+      - `public_key` set to the incoming `public_key` multiplied by `blinding_tweak`.
+      - `hop_payloads` set to the `unwrapped_payloads`, truncated to the incoming `hop_payloads` size.
+      - `hmac` set to `next_hmac`.
     - If it cannot forward:
       - MUST fail.
   - Otherwise (all-zero `next_hmac`):
     - This is the final destination of the onion.
 
-
 ## Rationale
 
-In the case where blinded paths are used, the sender did not actually encrypt this onion for our node_id, but for a tweaked version: we can derive the tweak used from `path_key` which is given alongside the onion.  Then we either tweak our node private key the same way to decrypt the onion, or tweak to the onion ephemeral key which is mathematically equivalent.
-
+In the case where blinded paths are used, the sender did not actually encrypt this onion for our `node_id`, but for a tweaked version: we can derive the tweak used from `path_key` which is given alongside the onion.  Then we either tweak our node private key the same way to decrypt the onion, or tweak to the onion ephemeral key which is mathematically equivalent.
 
 # Filler Generation
 

diff --git a/bolt04/blinded-onion-message-onion-test.json b/bolt04/blinded-onion-message-onion-test.json
@@ -6,12 +6,12 @@
     "hops": [
       {
         "alias": "Alice",
-        "comment": "Alice->Bob: note next_blinding_override to match that give by Dave for Bob",
-        "blinding_secret": "6363636363636363636363636363636363636363636363636363636363636363",
+        "comment": "Alice->Bob: note next_path_key_override to match that give by Dave for Bob",
+        "path_key_secret": "6363636363636363636363636363636363636363636363636363636363636363",
         "tlvs": {
           "next_node_id": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
-          "next_blinding_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
-          "blinding_override_secret": "0101010101010101010101010101010101010101010101010101010101010101"
+          "next_path_key_override": "031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
+          "path_key_override_secret": "0101010101010101010101010101010101010101010101010101010101010101"
         },
         "encrypted_data_tlv": "04210324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c0821031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f",
         "ss": "c04d2a4c518241cb49f2800eea92554cb543f268b4c73f85693541e86d649205",
@@ -26,7 +26,7 @@
       {
         "alias": "Bob",
         "comment": "Bob->Carol",
-        "blinding_secret": "0101010101010101010101010101010101010101010101010101010101010101",
+        "path_key_secret": "0101010101010101010101010101010101010101010101010101010101010101",
         "tlvs": {
           "next_node_id": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007",
           "unknown_tag_561": "123456"
@@ -44,7 +44,7 @@
       {
         "alias": "Carol",
         "comment": "Carol->Dave",
-        "blinding_secret": "f7ab6dca6152f7b6b0c9d7c82d716af063d72d8eef8816dfc51a8ae828fa7dce",
+        "path_key_secret": "f7ab6dca6152f7b6b0c9d7c82d716af063d72d8eef8816dfc51a8ae828fa7dce",
         "tlvs": {
           "padding": "0000000000",
           "next_node_id": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991"
@@ -62,7 +62,7 @@
       {
         "alias": "Dave",
         "comment": "Dave is final node, hence path_id",
-        "blinding_secret": "5de52bb427cc148bf23e509fdc18012004202517e80abcfde21612ae408e6cea",
+        "path_key_secret": "5de52bb427cc148bf23e509fdc18012004202517e80abcfde21612ae408e6cea",
         "tlvs": {
           "padding": "",
           "path_id": "deadbeefbadc0ffeedeadbeefbadc0ffeedeadbeefbadc0ffeedeadbeefbadc0",
@@ -82,8 +82,8 @@
   },
   "route": {
     "comment": "The resulting blinded route Alice to Dave.",
-    "introduction_node_id": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
-    "blinding": "031195a8046dcbb8e17034bca630065e7a0982e4e36f6f7e5a8d4554e4846fcd99",
+    "first_node_id": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
+    "first_path_key": "031195a8046dcbb8e17034bca630065e7a0982e4e36f6f7e5a8d4554e4846fcd99",
     "hops": [
       {
         "blinded_node_id": "02d1c3d73f8cac67e7c5b6ec517282d5ba0a52b06a29ec92ff01e12decf76003c1",