BOLT 4: Merge final_expiry_too_soon into incorrect_or_unknown_payment_details (#608)

In commit 914ebab908 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`]
+   * [`u32`:`height`]
 
-The `payment_hash` is unknown to the final node or the amount for that
+The `payment_hash` is unknown to the final node, the amount for that
-`payment_hash` is incorrect.
+`payment_hash` is incorrect or the CLTV expiry of the htlc is too close to the
+current block height for safe handling.
 
-Note: Originally PERM|16 (`incorrect_payment_amount`) was
+The `htlc_msat` parameter is superfluous, but left in for backwards
-used to differentiate incorrect final amount from unknown payment
+compatibility. The value of `htlc_msat` always matches the amount specified in
-hash. Sadly, sending this response allows for probing attacks whereby a node
+the final hop onion payload. It therefore does not have any informative value to
-which receives an HTLC for forwarding can check guesses as to its final
+the sender. A penultimate hop sending a different amount or expiry for the htlc
-destination by sending payments with the same hash but much lower values to
+is handled through `final_incorrect_cltv_expiry` and
-potential destinations and check the response.
+`final_incorrect_htlc_amount`.
 
-1. type: 17 (`final_expiry_too_soon`)
+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.
 
-The CLTV expiry is too close to the current block height for safe
+Note: Originally PERM|16 (`incorrect_payment_amount`) and PERM|17
-handling by the final node.
+(`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.