From 94c23ddffdc603d6c709749d013fd41764db3440 Mon Sep 17 00:00:00 2001 From: Matt David Date: Thu, 3 Dec 2015 17:24:29 -0800 Subject: [PATCH] Initial version of invoicerequest extension BIP --- bip-invoicerequest-extension.mediawiki | 167 +++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 bip-invoicerequest-extension.mediawiki diff --git a/bip-invoicerequest-extension.mediawiki b/bip-invoicerequest-extension.mediawiki new file mode 100644 index 00000000..e10355d4 --- /dev/null +++ b/bip-invoicerequest-extension.mediawiki @@ -0,0 +1,167 @@ +
+  BIP:     XXX
+  Title:   Out of Band Address Exchange using Encrypted PaymentRequests
+  Authors: Matt David 
+           Justin Newton 
+           Aaron Voisine 
+  Status:  Draft
+  Type:    Informational
+  Created: 2015-11-20
+
+ +==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== +{| +| Requestor || Entity Requesting ReturnPaymentRequest +- +| Responder || Entity Creating and Returning ReturnPaymentRequest +- +| Sender || Entity wishes to transfer value that they control (NOTE: This can be used interchangeably with requestor) +- +| Receiver || Entity receiving a value transfer (NOTE: This can be used interchangeably with responder) +|} + +===Acronyms=== +{| +| 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. + +
+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
+}
+
+ +{| +| 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. + +
+ 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;
+ }
+
+{| +| Field Name || Description +- +| encrypted_payment_request || AES-256-CBC Encrypted PaymentRequest +- +| receiver_public_key || Receiver's EC Public Key (SECP256K1) +- +| ephemeral_public_key || Ephemeral EC Public Key Derived from ECDH Key Exchange where X value used as exponent for Private Key creation (SECP256K1) +- +| payment_request_hash || SHA256 Hash of Non-Encrypted, Serialized PaymentRequest (used for validation) +|} + +==InvoiceRequest / ReturnPaymentRequest Process== + +# NOTE: The sender is the entity wishing to send value to the receiver. + +===Overview=== + +1. Sender creates InvoiceRequest message +2. Sender sends InvocieRequest to Receiver +3. Receiver validates InvoiceRequest +4. Receiver creates return PaymentRequest message +5. Receiver encrypts the PaymentRequest message +6. Receiver creates ReturnPaymentRequest +7. Receiver returns ReturnPaymentRequest message to Sender +8. Sender validates ReturnPaymentRequest +9. Sender decrypts and validates encrypted PaymentRequest + +===InvoiceRequest Message Creation=== + +* Create an InvoiceRequest message +* REQUIRED: Set sender_public_key. This is the public key of an EC keypair using secp256k1. +* Set amount if desired +* Set notification_url to URL that will accept ReturnPaymentRequest from Receiver +* 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 + +===ReturnPaymentRequest Message Creation and PaymentRequest Encryption=== + +* Generate EC secret point using [ECDH](https://en.wikipedia.org/wiki/Elliptic_curve_Diffie–Hellman) with the Sender's EC public key and the Receiver's EC private key. +* Generate Symmetric Encryption Key and Initialization vector using [HMAC_DRBG](http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf) also referenced in [RFC6979](https://tools.ietf.org/html/rfc6979) in the following way: +** HMAC_DRBG Initialization Entropy is set to the EC secret point's X value +** HMAC_DRBG Initialization Nonce is set to the InvoiceRequest's sender_public_key +** Encryption Key = HMAC_DRBG.GENERATE(32) - 256 bits +** IV = HMAC_DRBG.GENERATE(16) - 128 bits +* Encrypt the serialized PaymentRequest using AES-256-CBC using the Encryption Key and IV previously generated + +* 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) + + +===ReturnPaymentRequest Validation and Decryption=== + +* Generate EC secret point using [ECDH](https://en.wikipedia.org/wiki/Elliptic_curve_Diffie–Hellman) with the Sender's EC private key and the Receiver's EC public key. +* Generate Symmetric Decryption Key and Initialization vector using [HMAC_DRBG](http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf) also referenced in [RFC6979](https://tools.ietf.org/html/rfc6979) in the following way: +** HMAC_DRBG Initialization Entropy is set to the EC secret point's X value +** HMAC_DRBG Initialization Nonce is set to the InvoiceRequest's sender_public_key +** Encryption Key = HMAC_DRBG.GENERATE(32) - 256 bits +** IV = HMAC_DRBG.GENERATE(16) - 128 bits +* 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 using the Encryption Key and IV previously generated +* Validate payment_request_hash matches SHA256 of the decrypted, serialized PaymentRequest +* Deserialize the serialized PaymentRequest + +==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] \ No newline at end of file