diff --git a/concept-partial-payments.html b/concept-partial-payments.html index 2f4f54775d..885049def0 100644 --- a/concept-partial-payments.html +++ b/concept-partial-payments.html @@ -79,6 +79,7 @@
  • RippleAPI Beginners Guide
  • rippled Setup
  • Gateway Guide
    • +
  • Listing XRP as an Exchange
  • @@ -151,7 +152,8 @@
  • Partial Payment Limitations
  • The delivered_amount Field
  • Partial Payments Exploit
    • -
  • Avoiding the Exploit
    • +
  • Exploit Scenario Steps
    • +
  • Further Mitigations
    • @@ -195,8 +197,47 @@
  • Is included in a validated ledger before 2014-01-20

    • If both conditions are true, then delivered_amount contains the string value unavailable instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the AffectedNodes in the transaction's metadata. If the transaction delivered an issued currency and the issuer of the Amount is the same account as the Destination address, the delivered amount may be divided among multiple AffectedNodes members representing trust lines to different counterparties.

    +

    You can find the delivered_amount field in the following places:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    APIMethodField
    JSON-RPC / WebSocketaccount_tx commandresult.transactions array members' meta.delivered_amount
    JSON-RPC / WebSockettx commandresult.meta.delivered_amount
    JSON-RPC / WebSockettransaction_entry commandresult.metadata.delivered_amount
    RippleAPIgetTransaction methodoutcome.deliveredAmount
    RippleAPIgetTransactions methodarray members' outcome.deliveredAmount

    Partial Payments Exploit

    If a financial institution's integration with the Ripple Consensus Ledger assumes that the Amount field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.

    +

    The correct way to process incoming Payment transactions is to use the delivered_amount metadata field, not the Amount field. This way, an institution is never mistaken about how much it actually received.

    +

    Exploit Scenario Steps

    To exploit a vulnerable financial institution, a malicious actor does something like this:

    1. The malicious actor sends a Payment transaction to the institution. This transaction has a large Amount field and has the tfPartialPayment flag enabled.
      2. @@ -219,9 +260,8 @@
    2. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller delivered_amount in the Ripple Consensus Ledger.
    3. The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy.
    -

    Avoiding the Exploit

    -

    The simplest and most effective way to avoid partial payment exploits is to use the delivered_amount field of the transaction metadata, not the Amount field, when processing incoming transactions. This way, an institution is never mistaken about how much it actually received.

    -

    Additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example:

    +

    Further Mitigations

    +

    Using the delivered_amount field when processing incoming transactions is sufficient to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example: