BOLT 4: Merge final_expiry_too_soon into incorrect_or_unknown_payment…

…_details (#608)

In commit 914ebab the
incorrect_payment_amount error was merged into
incorrect_or_unknown_payment_details to prevent a probing attack
that allowed intermediate nodes to learn the final destination of
a payment.

A similar attack is possible using the htlc expiry value. By trying
payments with the correct amount but low expiry values to candidate
destinations, an incorrect_or_unknown_payment_details error can be
elicited. This would signal that the probe payment was sent to the
final destination.

For the intermediate node to determine the correct amount, an estimate
must be calculated. A logical choice would be the outgoing amount of the
intermediate node plus some allowance for routing fees that would
otherwise be paid to subsequent nodes along the path.

Picking a low enough - but not too low - expiry value is more tricky.
A reasonable guess could be made using external knowledge of the
final destination's implementation defaults or the type of invoice that
is paid to. Especially in the case of an hodl invoice that typically has
a large expiry delta, it is easier to make a correct guess.

This form of attack is arguably harder to realize than the amount probe
that was previously possible. The attacker may accidentally
pay the invoice if the expiry value guess satisfies the invoice
final cltv requirement. In that case, the attacker still has the
incoming htlc to pull which limits the loss.

04-onion-routing.md

@@ -825,21 +825,31 @@ handling by the processing node.
 1. type: PERM|15 (`incorrect_or_unknown_payment_details`)
 2. data:
    * [`u64`:`htlc_msat`]
-
-The `payment_hash` is unknown to the final node or the amount for that
-`payment_hash` is incorrect.
-
-Note: Originally PERM|16 (`incorrect_payment_amount`) was
-used to differentiate incorrect final amount from unknown payment
-hash. Sadly, sending this response allows for probing attacks whereby a node
-which receives an HTLC for forwarding can check guesses as to its final
-destination by sending payments with the same hash but much lower values to
-potential destinations and check the response.
-
-1. type: 17 (`final_expiry_too_soon`)
-
-The CLTV expiry is too close to the current block height for safe
-handling by the final node.
+   * [`u32`:`height`]
+
+The `payment_hash` is unknown to the final node, the amount for that
+`payment_hash` is incorrect or the CLTV expiry of the htlc is too close to the
+current block height for safe handling.
+
+The `htlc_msat` parameter is superfluous, but left in for backwards
+compatibility. The value of `htlc_msat` always matches the amount specified in
+the final hop onion payload. It therefore does not have any informative value to
+the sender. A penultimate hop sending a different amount or expiry for the htlc
+is handled through `final_incorrect_cltv_expiry` and
+`final_incorrect_htlc_amount`.
+
+The `height` parameter is set by the final node to the best known block height
+at the time of receiving the htlc. This can be used by the sender to distinguish
+between sending a payment with the wrong final CLTV expiry and an intermediate
+hop delaying the payment so that the receiver's invoice CLTV delta requirement
+is no longer met.
+
+Note: Originally PERM|16 (`incorrect_payment_amount`) and PERM|17
+(`final_expiry_too_soon`) were used to differentiate incorrect htlc parameters
+from unknown payment hash. Sadly, sending this response allows for probing
+attacks whereby a node which receives an HTLC for forwarding can check guesses
+as to its final destination by sending payments with the same hash but much
+lower values or expiry heights to potential destinations and check the response.
 
 1. type: 18 (`final_incorrect_cltv_expiry`)
 2. data:
@@ -942,7 +952,7 @@ An _intermediate hop_ MUST NOT, but the _final node_:
       altering the amount while not allowing for accidental gross overpayment.
   - if the `cltv_expiry` value is unreasonably near the present:
     - MUST fail the HTLC.
-    - MUST return a `final_expiry_too_soon` error.
+    - MUST return an `incorrect_or_unknown_payment_details` error.
   - if the `outgoing_cltv_value` does NOT correspond with the `cltv_expiry` from
   the final node's HTLC:
     - MUST return `final_incorrect_cltv_expiry` error.