diff options
Diffstat (limited to 'bip-0070.mediawiki')
| -rw-r--r-- | bip-0070.mediawiki | 37 |
1 files changed, 35 insertions, 2 deletions
diff --git a/bip-0070.mediawiki b/bip-0070.mediawiki index 692d7f0..433eb13 100644 --- a/bip-0070.mediawiki +++ b/bip-0070.mediawiki @@ -25,7 +25,7 @@ The current, minimal Bitcoin payment protocol operates as follows: This BIP extends the above protocol to support several new features: -# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address. +# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "example.com" instead of an inscrutable, 34-character bitcoin address. # Secure proof of payment, which the customer can use in case of a dispute with the merchant. # Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet. # Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment. @@ -99,6 +99,12 @@ about the merchant and a digital signature. | merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address. |} +The payment_url specified in the PaymentDetails should remain valid at least until the PaymentDetails +expires (or as long as possible if the PaymentDetails does not expire). Note that this is irrespective of +any state change in the underlying payment request; for example cancellation of an order should not +invalidate the payment_url, as it is important that the merchant's server can record mis-payments +in order to refund the payment. + A PaymentRequest is PaymentDetails optionally tied to a merchant's identity: <pre> message PaymentRequest { @@ -118,7 +124,11 @@ A PaymentRequest is PaymentDetails optionally tied to a merchant's identity: |- | serialized_payment_details || A protocol-buffer serialized PaymentDetails message. |- -| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data. +| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, +with all serialized fields serialized in numerical order (all current protocol buffer implementations serialize +fields in numerical order) and signed using the public key in pki_data. Optional fields that are not set +are not serialized (however, setting a field to its default value will cause it to be serialized and will affect +the signature). Before serialization, the signature field must be set to an empty value so that the field is included in the signed PaymentRequest hash but contains no data. |} When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following: @@ -153,10 +163,18 @@ after the time of the payment request. After that time has expired, parties must If the customer authorizes payment, then the Bitcoin client: # Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs +# Validate that customer's system unix time (UTC) is still before PaymentDetails.expires. If it is not, the payment should be cancelled. # Broadcast the transactions on the Bitcoin p2p network. # If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request. Errors communicating with the payment_url server should be communicated to the user. +In the scenario where the merchant's server receives multiple identical Payment +messages for an individual PaymentRequest, it must acknowledge each. The second +and further PaymentACK messages sent from the merchant's server may vary by memo +field to indicate current state of the Payment (for example number of confirmations +seen on the network). This is required in order to ensure that in case of a transport +level failure during transmission, recovery is possible by the Bitcoin client +re-sending the Payment message. PaymentDetails.payment_url should be secure against man-in-the-middle attacks that might alter Payment.refund_to (if using HTTP, it must be @@ -173,6 +191,9 @@ determine whether or not the transactions satisfy conditions of payment. If and only if they do, if should broadcast the transaction(s) on the Bitcoin p2p network. +Payment messages larger than 50,000 bytes should be rejected by +the merchant's server, to mitigate denial-of-service attacks. + ===PaymentACK=== PaymentACK is the final message in the payment protocol; it is sent @@ -190,6 +211,11 @@ Payment message: | memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.") |} +PaymentACK messages larger than 60,000 bytes should be rejected by +the wallet application, to mitigate denial-of-service attacks. This +is larger than the limits on Payment and PaymentRequest messages +as PaymentACK contains a full Payment message within it. + ==Localization== Merchants that support multiple languages should generate @@ -270,6 +296,13 @@ http://datatracker.ietf.org/wg/pkix/charter/ Protocol Buffers : https://developers.google.com/protocol-buffers/ +==Reference implementation== + +Create Payment Request generator : https://bitcoincore.org/~gavin/createpaymentrequest.php +Sources at : https://bitcoincore.org/~gavin/createpaymentrequest.php + +BitcoinJ : https://bitcoinj.github.io/payment-protocol#introduction + ==See Also== Javascript Object Signing and Encryption working group : |