lnd/docs/SphinxReplayDB.md

Sphinx Onion Routing in Lightning Network

The Lightning Network uses a Sphinx-based onion message protocol to send messages across the Lightning Network. These messages have the property that a node which is part of such a message and for example forwards such an onion message cannot learn about the destination of this whole packet. It only knows the predecessor and the successor of the message. In other words, it only knows where the message came from and where it needs to be forwarded. This makes the message protocol of the Lightning Network very private. Only the sender (creator of the whole onion packet) knows the whole route of the packet. Also, the receiver has no idea from which node the message originated.

This diagram illustrates how Sphinx onion routing works in the Lightning Network, showing the privacy properties at each hop:

Alice (Sender)
    |
    | Knows Full Route: Alice → Bob → Carol → David → Eve
    |
    v
Bob (Hop 1)
    |
    | Knows: Alice → Carol
    |
    v
Carol (Hop 2)
    |
    | Knows: Bob → David
    |
    v
David (Hop 3)
    |
    | Knows: Carol → Eve
    |
    v
Eve (Receiver)
    |
    | Knows: From David
    |
    v

Privacy Properties:
- Each hop only knows its immediate neighbors
- Receiver doesn't know the original sender
- Only sender knows the complete route
- Each hop peels one layer of the onion

Privacy Properties

1. Hop Privacy: Each intermediate node only knows:

   • The previous hop (where the packet came from)
   • The next hop (where to forward the packet)
   • Cannot see the full route or final destination

2. Sender Privacy: Only the sender (Alice) knows:

   • The complete route
   • All intermediate nodes
   • The final destination

3. Receiver Privacy: The receiver (Eve) only knows:

   • The immediate previous hop (David)
   • Cannot determine the original sender

4. Onion Encryption: Each hop peels one layer of encryption, revealing only the next hop's information

The detailed mechanics are described in BOLT 04

Replaying Onion Packets

The sphinx protocol clearly states that implementations of the protocol should guard against replay attacks. Replaying (resending) onion packets into the network can compromise the privacy guarantees promised by the protocol. So it is crucial for node participants to not forward replayed onion packets to guard the privacy of all network participants. Compared to the original Sphinx protocol, the Lightning Network has an improved replay protection in place especially when it comes to forwarding HTLCs, which are different from Onion Messages introduced later on because HTLCs lock a payment to the particular onion packet. Therefore, sending HTLCs packets comes with a cost. Moreover, every HTLC has an expiry date, also called CLTV (absolute locktime), which prevents the replay of packets that have already expired. In addition to the CLTV expiry of a packet, every HTLC onion packet commits to the payment hash in the HMAC of the message (to be precise, the associated data), so this prevents an attacker from attaching an old onion packet to a new payment hash, which now also comes with the risk for the attacker that he does not only have to lock funds when replaying an onion packet but he also risks that the next node settles the HTLC because it already knows the preimage of the HTLC. Although the attack comes with a high cost, Lightning implementations should prevent replayed onion packets from propagating through the network to safeguard the privacy for every network participant.

Replay attack

An attacker could execute a re-injection attack by strategically positioning well-connected nodes within the network, ensuring they participate in a high volume of payment forwarding. In this scenario, the attacker's nodes act as forwarding intermediaries. These malicious nodes would collect passing onion packets and concurrently monitor network gossip. Upon observing a successful payment forward, the attacker could re-inject the captured onion message. By then monitoring channel updates or closures from the neighboring node, the attacker aims to determine if that channel was part of the payment path. Furthermore, if the neighboring node, lacking a suitable outgoing channel, instead settles the payment (i.e., acts as the final recipient), it becomes highly probable that it was the ultimate receiving node. It's important to note, however, that such an attack carries significant costs.

Replay Protection in LND

In LND there are two interchanging DB names which save information of those onion packets to prevent replays from happening. They are called Sphinx-Replay-DB or Decayed-Log-DB. Currently LND only implements onion messages which are tied to payments (i.e. HTLCs), and as explained above, HTLCs expire after an absolute lock time and therefore can be garbage collected because they will not be forwarded by nodes anyways as that would entail a risk of losing funds.

Sphinx replay protection storage for the different backends:

1. When running LND with the BBolt backend the db is called: sphinxreplay.db.

2. For Postgres the table is called: decayedlogdb_kv.

3. For SQLite the table is called decayedlogdb_kv and is part of the channel.sqlite file.

LND employs an internal stores to prevent replay attacks. The internal store maintains a record of each onion packet's shared secret alongside its absolute timelock (CLTV). This enables LND to efficiently identify and discard replayed packets that present an already-seen shared secret.

This store is subject to garbage collection, ensuring it does not impose a sustained burden on memory resources. After the CLTV values expiry, the entries can be removed as described earlier.

What happens if LND encounters a replayed onion HTLC packet?

When LND encounters a replay, it will reject the HTLC and it will not signal a specific error that a replay occurred which would reveal that the node was indeed part of the route in the onion packet. LND will reject the HTLC and respond with the message invalid_onion_version. See BOLT 04

Other attacks

In the Lightning Network, the Sphinx protocol effectively mitigates tagging attacks. This is due to the fact that each onion packet incorporates a cryptographic HMAC (Hash-based Message Authentication Code), which is derived from the packet's encrypted contents. Consequently, any attempt to tamper with the packet's data would render its HMAC invalid, causing the packet to be discarded by honest nodes.