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+ +==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. + ++ Justin Newton + Aaron Voisine + Status: Draft + Type: Informational + Created: 2015-11-20 +
+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