diff --git a/04-onion-routing.md b/04-onion-routing.md index 1a187870e..87eeebe32 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -204,7 +204,7 @@ This is formatted according to the Type-Length-Value format defined in [BOLT #1] * [`tu64`:`total_msat`] 1. type: 10 (`encrypted_recipient_data`) 2. data: - * [`...*byte`:`encrypted_data`] + * [`...*byte`:`encrypted_recipient_data`] 1. type: 12 (`current_path_key`) 2. data: * [`point`:`path_key`] @@ -516,9 +516,8 @@ The reader of the `blinded_path`: - MUST include the corresponding `encrypted_recipient_data` in each onion payload within `path` - For the first entry in `path`: - if it is sending a payment: - - MAY encrypt the first blinded path onion to `first_node_id` and include `first_path_key` as `current_path_key`. - - MUST use this method if the prior node does not support `option_route_blinding`. - - if it does not do that: + - SHOULD create an unblinded onion payment to `first_node_id`, and include `first_path_key` as `current_path_key`. + - otherwise: - MUST encrypt the first blinded path onion to the first `blinded_node_id`. - MUST set `next_path_key_override` in the prior onion payload to `first_path_key`. - For each successive entry in `path`: @@ -533,7 +532,7 @@ The reader of the `encrypted_recipient_data`: - MUST decrypt the `encrypted_recipient_data` field using $`rho_i`$ as a key using ChaCha20-Poly1305 and an all-zero nonce key. - If the `encrypted_recipient_data` field is missing, cannot be decrypted into an `encrypted_data_tlv` or contains unknown even fields: - MUST return an error -- If `encrypted_data` contains a `next_path_key_override`: +- If the `encrypted_data_tlv` contains a `next_path_key_override`: - MUST use it as the next `path_key`. - Otherwise: - MUST use $`E_{i+1} = SHA256(E_i || ss_i) * E_i`$ as the next `path_key` @@ -557,7 +556,12 @@ the onion and the `encrypted_recipient_data` payload. When concatenating two blinded routes generated by different nodes, the last node of the first route needs to know the first `path_key` of the second route: the `next_path_key_override` field must be used to transmit this -information. +information. In theory this method could be used for payments (not just +onion messages), but we recommend using an unblinded path to reach the +`first_node_id` and using `current_path_key` there: this means that the +node can tell it is being used as an introductory point, but also does +not require blinded path support on the nodes to reach that point, and +gives meaningful errors on the unblinded part of the payment. 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 @@ -575,7 +579,7 @@ should add a random delay before forwarding the error. Failures are likely to be probing attempts and message timing may help the attacker infer its distance to the final recipient. -The `padding` field can be used to ensure that all `encrypted_data` have the +The `padding` field can be used to ensure that all `encrypted_recipient_data` have the same length. It's particularly useful when adding dummy hops at the end of a blinded route, to prevent the sender from figuring out which node is the final recipient. @@ -591,7 +595,7 @@ payments (which could be used to unblind nodes inside the route). ### Inside `encrypted_recipient_data`: `encrypted_data_tlv` -The `encrypted_data` is a TLV stream, encrypted for a given blinded node, that +The `encrypted_recipient_data` is a TLV stream, encrypted for a given blinded node, that may contain the following TLV fields: 1. `tlv_stream`: `encrypted_data_tlv` @@ -627,7 +631,7 @@ may contain the following TLV fields: #### Rationale Encrypted recipient data is created by the final recipient to give to the -payer, containing instructions for the node on how to handle the message. It's used +sender, containing instructions for the node on how to handle the message (it can also be created by the sender themselves: the node forwarding cannot tell). It's used in both payment onions and onion messages onions. See [Route Blinding](#route-blinding). @@ -1491,7 +1495,7 @@ For consistency, all onion messages use [Route Blinding](#route-blinding). * `filler` The `onionmsg_tlv` itself is a TLV: an intermediate node expects an -`encrypted_data` which it can decrypt into an `encrypted_data_tlv` +`encrypted_recipient_data` which it can decrypt into an `encrypted_data_tlv` using the `path_key` which it is handed along with the onion message. Field numbers 64 and above are reserved for payloads for the final