mirror of
https://github.com/bitcoin/bips.git
synced 2025-01-18 21:35:13 +01:00
169 lines
7.3 KiB
Plaintext
169 lines
7.3 KiB
Plaintext
<pre>
|
||
BIP: XXX
|
||
Title: Out of Band Address Exchange using Encrypted PaymentRequests
|
||
Authors: Matt David <matt@netki.com>
|
||
Justin Newton <justin@netki.com>
|
||
Aaron Voisine <aaron@breadwallet.com>
|
||
Status: Draft
|
||
Type: Informational
|
||
Created: 2015-11-20
|
||
</pre>
|
||
|
||
==Abstract==
|
||
|
||
This BIP is an extension to BIP70 the extends the payment protocol to prevent PaymentRequet interception / modification
|
||
during transmission using ephemeral key encryption, allow permissioned release of PaymentRequests to PaymentRequest requestors
|
||
and, allow a requestor to supply a certificate and signature to the PaymentRequest creator.
|
||
|
||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
|
||
"OPTIONAL" in this document are to be interpreted as described in RFC 2119.
|
||
|
||
==Motivation==
|
||
|
||
The motiviation for defining this extension to the BIP-70 Payment Protocol is to allow 2 parties to exchange payment
|
||
information in a permissioned and encrypted way such that wallet address communication can become a more automated process.
|
||
Additionally, this extension allows for the requestor of a PaymentRequest to supply a certificate and signature in order
|
||
to facilitate identification for address release.
|
||
|
||
==Definitions==
|
||
{| class="wikitable"
|
||
| Sender || Entity wishes to transfer value that they control
|
||
|-
|
||
| Receiver || Entity receiving a value transfer
|
||
|}
|
||
|
||
===Acronyms===
|
||
{| class="wikitable"
|
||
! Acronym !! Expanded !! Description
|
||
|-
|
||
| IR || InvoiceRequest || A request to create a PaymentRequest
|
||
|-
|
||
| RPR || ReturnPaymentRequest || A ReturnPaymentRequest returned based on a submitted InvoiceRequest
|
||
|}
|
||
|
||
===New Messages===
|
||
|
||
====InvoiceRequest====
|
||
The new InvoiceRequest message allows a requestor to send information to the responder such that they can return a ReturnPaymentRequest.
|
||
|
||
<pre>
|
||
message InvoiceRequest {
|
||
required bytes sender_public_key = 1; // Sender's EC Public Key
|
||
optional uint64 amount = 2 [default = 0]; // amount is integer-number-of-satoshis
|
||
optional string pki_type = 3 [default = "none"]; // none / x509+sha256
|
||
optional bytes pki_data = 4; // Depends on pki_type
|
||
optional string notification_url = 5; // URL to notify on ReturnPaymentRequest ready
|
||
optional bytes signature = 6; // PKI-dependent signature
|
||
}
|
||
</pre>
|
||
|
||
{| class="wikitable"
|
||
! Field Name !! Description
|
||
|-
|
||
| sender_public_key || Sender's EC Public Key
|
||
|-
|
||
| amount || amount is integer-number-of-satoshis (default: 0)
|
||
|-
|
||
| pki_type || none / x509+sha256 (default: "none")
|
||
|-
|
||
| pki_data || Depends on pki_type
|
||
|-
|
||
| notification_url || URL to notify on ReturnPaymentRequest ready
|
||
|-
|
||
| signature || PKI-dependent signature
|
||
|}
|
||
|
||
====ReturnPaymentRequest====
|
||
|
||
The new ReturnPaymentRequest message is an encapsulating message that allows the transmission of an encrypted, serialized PaymentRequest.
|
||
|
||
<pre>
|
||
message ReturnPaymentRequest {
|
||
required bytes encrypted_payment_request = 1;
|
||
required bytes receiver_public_key = 2;
|
||
required bytes ephemeral_public_key = 3;
|
||
required bytes payment_request_hash = 4;
|
||
}
|
||
</pre>
|
||
{| class="wikitable"
|
||
! Field Name</b> !! Description
|
||
|-
|
||
| encrypted_payment_request || AES-256-CBC Encrypted Serialized PaymentRequest
|
||
|-
|
||
| receiver_public_key || Receiver's EC Public Key
|
||
|-
|
||
| ephemeral_public_key || Ephemeral EC Public Key
|
||
|-
|
||
| payment_request_hash || SHA256 Hash of Non-Encrypted, Serialized PaymentRequest
|
||
|}
|
||
|
||
==InvoiceRequest / ReturnPaymentRequest Process==
|
||
|
||
===Overview===
|
||
|
||
# Sender [[#ir-creation|creates]] InvoiceRequest
|
||
# Sender transmits InvoiceRequest to Receiver
|
||
# Receiver [[#ir-validation|validates]] InvoiceRequest
|
||
# Receiver creates PaymentRequest
|
||
# Receiver [[#rpr-creation-encryption|encrypts]] the PaymentRequest
|
||
# Receiver [[#rpr-creation-encryption|creates]] ReturnPaymentRequest (containing an encrypted PaymentRequest)
|
||
# Receiver transmits ReturnPaymentRequest to Sender
|
||
# Sender validates ReturnPaymentRequest
|
||
# Sender [[#rpr-validation-pr-decryption|decrypts and validates]] encrypted PaymentRequest
|
||
|
||
<span id="ir-creation"></span>
|
||
===InvoiceRequest Message Creation===
|
||
|
||
* Create an InvoiceRequest message
|
||
* sender_public_key MUST be set. This is the public key of an EC keypair using secp256k1.
|
||
* Set amount if desired
|
||
* Set notification_url to URL that Receiver will submit completed ReturnPaymentRequest to
|
||
* If NOT including certificate, set pki_type to "none"
|
||
* If including certificate:
|
||
** Set pki_type to "x509+sha256"
|
||
** Set pki_data as it would be set in BIP-0070 (see [Certificates](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#Certificates) section)
|
||
** Sign InvoiceRequest with signature == "" using the X509 Certificate's private key
|
||
|
||
<span id="ir-validation"></span>
|
||
===InvoiceRequest Validation===
|
||
|
||
* Validate sender_public_key is a valid EC public key
|
||
* Validate notification_url if set, contains characters deemed valid for a URL (avoiding XSS related characters, etc).
|
||
* If pki_type is None, InvoiceRequest is VALID
|
||
* If pki_type is x509+sha256 and signature is valid for the serialized InvoiceRequest where signature is set to "", InvoiceRequest is VALID
|
||
|
||
<span id="rpr-creation-encryption"></span>
|
||
===ReturnPaymentRequest Message Creation and PaymentRequest Encryption===
|
||
|
||
* Encrypt the serialized PaymentRequest using AES-256-CBC setup as described in [[#ECDH-AES-Setup ECDH Point Generation and AES-256 (CBC Mode) Setup]]
|
||
* Create ReturnPaymentRequest message
|
||
* Set encrypted_payment_request to be the encrypted value of the PaymentRequest
|
||
* Set receiver_public_key to the Receiver's EC public key (of which the private key was previously used in ECDH secret point calculation)
|
||
* Set ephemeral_public_key to the public key of an EC keypair created using the secret point's X value.
|
||
* Set payment_request_hash to generated SHA256 hash of the serialized PaymentRequest (without encryption)
|
||
|
||
<span id="rpr-validation-pr-decryption"></span>
|
||
===ReturnPaymentRequest Validation and Decryption===
|
||
|
||
* Validate ephemeral_public_key matches public key of an EC keypair created using the secret point's X value.
|
||
* Decrypt the serialized PaymentRequest using AES-256-CBC setup as described in [[#ECDH-AES-Setup ECDH Point Generation and AES-256 (CBC Mode) Setup]]
|
||
* Validate payment_request_hash matches SHA256 of the decrypted, serialized PaymentRequest
|
||
* Deserialize the serialized PaymentRequest
|
||
|
||
{{anchor|ECDH-AES-Setup}}
|
||
===ECDH Point Generation and AES-256 (CBC Mode) Setup===
|
||
|
||
* Generate the '''secret point''' using [https://en.wikipedia.org/wiki/Elliptic_curve_Diffie–Hellman ECDH] using the local entity's private key and the remote entity's public key as inputs.
|
||
* Initialize [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf HMAC_DRBG]
|
||
** Use '''secret point's''' X value for Entropy
|
||
** Use Sender's public key for Nonce
|
||
* Initialize AES-256 in CBC Mode
|
||
** Use HMAC_DRBG.GENERATE(32) as the Encryption Key (256 bits)
|
||
** Use HMAC_DRBG.GENERATE(16) as the Initialization Vector (IV) (128 bits)
|
||
|
||
==Reference==
|
||
|
||
* [[bip-0070.mediawiki|BIP70 - Payment Protocol]]
|
||
* [https://en.wikipedia.org/wiki/Elliptic_curve_Diffie–Hellman ECDH]
|
||
* [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf HMAC_DRBG]
|
||
* [https://tools.ietf.org/html/rfc6979 RFC6979] |