bitcoin-bips/bip-invoicerequest-extension.mediawiki

<pre>
  BIP:     XXX
  Title:   Out of Band Address Exchange using Encrypted PaymentRequests
  Authors: Justin Newton <justin@netki.com>
           Matt David <mgd@mgddev.com>
           Aaron Voisine <voisine@gmail.com>
           James MacWhyte <macwhyte@gmail.com>
  Status:  Draft
  Type:    Informational
  Created: 2015-11-20
</pre>

==Abstract==

This BIP is an extension to BIP 70 that provides two enhancements to the existing Payment Protocol.

# It allows the requestor (Sender) of a Payment Request to voluntarily sign the original request and provide a certificate to allow the payee to know the identity of who they are transacting with. 

# It encrypts the Payment Request that is returned, before handing it off to the SSL/TLS layer to prevent man in the middle viewing of the Payment Request details.

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.

==Definitions==
{| class="wikitable"
| Sender    || Entity wishing to transfer value that they control
|-
| Receiver  || Entity receiving a value transfer
|}

==Motivation==

The motivation for defining this extension to the BIP70 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. This also allows for automated creation of off blockchain transaction logs that are human readable, containing who you transacted with, in addition to the information that it contains today.

The motivation for this extension to BIP70 is threefold:

# Ensure that the payment details can only be seen by the participants in the transaction, and not by any third party.  

# Enhance the Payment Protocol to allow for store and forward servers in order to allow, for example, mobile wallets to sign and serve Payment Requests.

# Allow a sender of funds the option of sharing their identity with the receiver.  This information could then be used to:

#* Make bitcoin logs more human readable 
#* Give the user the ability to decide who to release payment details to 
#* Allow an entity such as a political campaign to ensure donors match regulatory and legal requirements 
#* Allow for an open standards based way to meet regulatory requirements
#* Automate the active exchange of payment addresses, so static addresses and BIP32 X-Pubs can be avoided to maintain privacy and convenience

In short we wanted to make bitcoin more human, while at the same time improving transaction privacy.

==Example Use Cases==

1. Address Book

A Bitcoin wallet developer would like to offer the ability to store an "address book" of payees, so users could 
send multiple payments to known entities without having to request an address every time. Static addresses compromise 
privacy, and address reuse is considered a security risk. BIP32 X-Pubs allow the generation of unique addresses, but 
watching an X-Pub chain for each person you wish to receive funds from is too resource-intensive for mobile applications, 
and there is always a risk of unknowingly sending funds to an X-Pub address after the owner has lost access to the 
corresponding private key.

With this BIP, Bitcoin wallets could maintain an "address book" that only needs to store each payee's public key. Adding 
an entry to one's address book could be done by using a Wallet Name, scanning a QR code, sending a URI through a text message or e-mail, or 
searching a public repository. When the user wishes to make a payment, their wallet would do all the work in the background 
to communicate with the payee's wallet to receive a unique payment address. If the payee's wallet has been lost, replaced, 
or destroyed, no communication will be possible, and the sending of funds to a "dead" address is prevented.

2. Individual Permissioned Address Release

A Bitcoin wallet developer would like to allow users to view a potential sending party's identifying information before deciding whether or not to share payment information with them. Currently, BIP70 specifies that the Merchant Server respond to a "pay now" style request with a PaymentRequest, releasing address and X.509 certificate identity information of the potential receiving party.

With this BIP, Bitcoin wallets could prompt a wallet user to release payment information while displaying identity 
information about the potential sending party via an included certificate. This gives the receiving party more control over who receives their payment and identity information, and could be helpful for businesses that need to follow KYC policies or wallets that want to focus on privacy.

3. Using Store & Forward Servers

A Bitcoin wallet developer would like to use a public Store & Forward service for an asynchronous address 
exchange. This is a common case for mobile and offline wallets.

With this BIP, returned payment information is encrypted with an ECDH-computed shared key before sending to a Store & Forward 
service. In this case, a successful attack against a Store & Forward service would not be able to read or modify wallet address 
or payment information, only delete encrypted messages.
[MATT PLEASE INCLUDE TEXT HERE REGARDING OTHER STORE AND FORWARD MODIFICATIONS]

==New Messages==

===EncryptedInvoiceRequest===
The EncryptedInvoiceRequest message allows a Sender to send an encrypted InvoiceRequest to the Receiver such that the details of the InvoiceRequest are kept secret.
<pre>
message EncryptedInvoiceRequest {
    required bytes encrypted_invoice_request = 1;
    required bytes sender_public_key = 2;
    required bytes invoice_request_hash = 3;
}
</pre>

{| class="wikitable"
! Field Name</b> !! Description
|-
| encrypted_invoice_request || AES-256-CBC encrypted, serialized InvoiceRequest
|-
| sender_public_key       || Sender's EC public key
|-
| invoice_request_hash      || SHA256 Hash of non-encrypted, serialized InvoiceRequest
|}

===InvoiceRequest===
The InvoiceRequest message allows a Sender to send information to the Receiver such that they can create and return a EncryptedPaymentRequest.

<pre>
message InvoiceRequest {
        required bytes  sender_public_key = 1;
        required uint64 nonce = 2;
        optional uint64 amount = 3 [default = 0];
        optional string pki_type = 4 [default = "none"];
        optional bytes  pki_data = 5;
        optional string notification_url = 6;
        optional bytes  signature = 7;
}
</pre>

{| class="wikitable"
! Field Name !! Description
|-
| sender_public_key     || Sender's EC public key
|-
| nonce                 || Microseconds since epoch
|-
| amount                || amount is integer-number-of-satoshis (default: 0)
|-
| pki_type              || none / x509+sha256 (default: "none")
|-
| pki_data              || Depends on pki_type
|-
| notification_url      || Secure (usually HTTPS) location where an EncryptedPaymentRequest (see below) SHOULD be sent when ready
|-
| signature             || PKI-dependent signature
|}

===EncryptedPaymentRequest===

The EncryptedPaymentRequest message is an encapsulating message that allows the transmission of an encrypted, serialized PaymentRequest.

<pre>
message EncryptedPaymentRequest {
        required bytes encrypted_payment_request = 1;
        required bytes receiver_public_key = 2;
        required bytes payment_request_hash = 3;
}
</pre>
{| class="wikitable"
! Field Name</b> !! Description
|-
| encrypted_payment_request || AES-256-CBC encrypted, serialized PaymentRequest
|-
| receiver_public_key       || Receiver's EC public key
|-
| payment_request_hash      || SHA256 Hash of non-encrypted, serialized PaymentRequest
|}

===EncryptedPayment===

The EncryptedPayment message allows a BIP70 Payment message to be transmitted through a third party without revealing the details of the transaction. This message allows Store & Forward servers or other third parties to match and authenticate PaymentRequest and Payment messages without revealing the details of the transaction, thereby protecting privacy.

<pre>
message EncryptedPayment {
        required bytes encrypted_payment = 1;
        required bytes payment_request_hash = 2;
        required bytes signature = 3;
}
</pre>
{| class="wikitable"
! Field Name</b> !! Description
|-
| encrypted_payment         || A standard BIP70 Payment message, serialized and encrypted with the payee's public key
|-
| payment_request_hash      || SHA256 Hash of original non-encrypted, serialized PaymentRequest. Some other identifier linking this message to the original request can also be used.
|-
| signature                 || A signature of this message, serialized with a value of "" for signature.
|}

===EncryptedPaymentACK===

An encrypted version of the BIP70 PaymentAck.

<pre>
message EncryptedPaymentACK {
        required bytes encrypted_payment_ack = 1;
        required bytes payment_request_hash = 2;
        required bytes signature = 3;
}
</pre>
{| class="wikitable"
! Field Name</b> !! Description
|-
| encrypted_payment         || A standard BIP70 PaymentACK message, serialized and encrypted with the payer's public key
|-
| payment_request_hash      || The payment_request_hash provided in the EncryptedPayment message.
|-
| signature                 || A signature of this message, serialized with a value of "" for signature.
|}

==InvoiceRequest / PaymentRequest Process==
The process overview for using InvoiceRequests and receiving encrypted PaymentRequests is defined below in two sections. 
Optionally, the Sender MAY choose to encrypt the InvoiceRequest message and therefore MUST follow the <b>Encrypted InvoiceRequest Overview</b> process.

===Non-Encrypted InvoiceRequest Overview===
# Sender creates InvoiceRequest
# Sender transmits InvoiceRequest to Receiver
# Receiver validates InvoiceRequest
# Receiver creates PaymentRequest
# Receiver encrypts the PaymentRequest
# Receiver creates EncryptedPaymentRequest (containing an encrypted PaymentRequest)
# Receiver transmits EncryptedPaymentRequest to Sender
# Sender validates EncryptedPaymentRequest
# Sender decrypts and validates encrypted PaymentRequest
# The PaymentRequest is processed according to BIP70, including optional Payment and PaymentACK messages


<img src="bip-ir/invoice-request-process.png"></img>

===Encrypted InvoiceRequest Overview===
# Sender retrieves Receiver InvoiceRequest Public Key
# Sender creates InvoiceRequest
# Sender encrypts the InvoiceRequest
# Sender creates EncryptedInvoiceRequest (containing an encrypted InvoiceRequest)
# Sender transmits EncryptedInvoiceRequest to Receiver
# Receiver decrypts and validates EncryptedInvoiceRequest
# Receiver validates InvoiceRequest
# Receiver creates PaymentRequest
# Receiver encrypts the PaymentRequest
# Receiver creates EncryptedPaymentRequest (containing an encrypted PaymentRequest)
# Receiver transmits EncryptedPaymentRequest to Sender
# Sender validates EncryptedPaymentRequest
# Sender decrypts and validates encrypted PaymentRequest
# The PaymentRequest is processed according to BIP70, including optional EncryptedPayment and EncryptedPaymentACK messages

<b>NOTE:</b> See section <b>Initial Public Key Retrieval for InvoiceRequest Encryption</b> below for possible options to retrieve Receiver InvoiceRequest public keys.

<img src="bip-ir/encrypted-invoice-request-process.png"></img>

==Message Interaction Details==

===EncryptedInvoiceRequest===
Sender MUST transmit EncryptedInvoiceRequest to Receiver (or Receiver's agent) via TLS-protected HTTP. Sender transmitting
EncryptedInvoiceRequest message MUST set appropriate Content-Type headers as specified here:
<pre>Content-Type: application/bitcoin-encrypted-invoicerequest</pre>

===InvoiceRequest===
Sender MUST transmit InvoiceRequest to Receiver (or Receiver's agent) via TLS-protected HTTP. Sender transmitting
InvoiceRequest message MUST set appropriate Content-Type headers as specified here:
<pre>Content-Type: application/bitcoin-invoicerequest</pre>

===EncryptedPaymentRequest===
Receiver MUST transmit EncryptedPaymentRequest to Sender (or Sender's agent) via TLS-protected HTTP. Receiver transmitting
EncryptedPaymentRequest messages MUST set appropriate Content-Type headers as specified here:
<pre>Content-Type: application/bitcoin-encrypted-paymentrequest</pre>

===EncryptedPayment===
Receiver MUST transmit EncryptedPayment to Sender (or Sender's agent) via TLS-protected HTTP. Receiver transmitting
EncryptedPayment messages MUST set appropriate Content-Type headers as specified here:
<pre>Content-Type: application/bitcoin-encrypted-payment</pre>

===EncryptedPaymentACK===
Receiver MUST transmit EncryptedPaymentACK to Sender (or Sender's agent) via TLS-protected HTTP. Receiver transmitting
EncryptedPaymentACK messages MUST set appropriate Content-Type headers as specified here:
<pre>Content-Type: application/bitcoin-encrypted-paymentack</pre>

===Message or Communication Errors===
An invalid or unparsable message or communications error MUST be communicated to the party that initiated the communication. This
SHOULD be done through standard HTTP Status Code messaging ([https://tools.ietf.org/html/rfc7231 RFC 7231 Section 6]).

==Process Step Details==

===InvoiceRequest Message Creation===
* Create an InvoiceRequest message
* sender_public_key MUST be set to the public key of an EC keypair
* nonce MUST be set to a non-repeating number. The current epoch time in microseconds SHOULD be used, unless the creating device doesn't have access to a RTC (in the case of a smart card, for example)
* Amount is optional. If the amount is not specified by the InvoiceRequest, the Receiver MAY specify the amount in the returned PaymentRequest. If an amount is specified by the InvoiceRequest and a PaymentRequest cannot be generated for that amount, the InvoiceRequest SHOULD be rejected with HTTP status code 406.
* Set notification_url to URL that the Receiver will submit completed EncryptedPaymentRequest 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 [https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#Certificates Certificates]) section)
** Sign InvoiceRequest with signature = "" using the X509 Certificate's private key
** Set signature value to the computed signature

===EncryptedInvoiceRequest Message Creation===
* Create an EncryptedInvoiceRequest
* Retrieve endpoint public key to use in <b>ECDH Point Generation</b> as specified in <b>Initial Public Key Retrieval for InvoiceRequest Encryption</b> (see below)
* sender_public_key MUST be set to the public key of an EC keypair
* invoice_request_hash MUST be set to the SHA256 hash of the serialized InvoiceRequest (without encryption)
* Encrypt the serialized InvoiceRequest using AES-256-CBC setup as described in <b>ECDH Point Generation and AES-256 (CBC Mode) Setup (see below)</b>
* encrypted_invoice_Request MUST be set to the encrypted values of the InvoiceRequest

===InvoiceRequest Validation===
* Validate sender_public_key is a valid EC public key
* The nonce MUST not be repeated. The service receiving the InvoiceRequest MAY use whatever method to make sure that the nonce is never repeated. 
* 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

===EncryptedPaymentRequest Message Creation and PaymentRequest Encryption===
* Encrypt the serialized PaymentRequest using AES-256-CBC setup as described in <b>ECDH Point Generation and AES-256 (CBC Mode) Setup (see below)</b>
* Create EncryptedPaymentRequest 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 payment_request_hash to generated SHA256 hash of the serialized PaymentRequest (without encryption)

===EncryptedPaymentRequest Validation and Decryption===
* Decrypt the serialized PaymentRequest using AES-256-CBC setup as described in <b>ECDH Point Generation and AES-256 (CBC Mode) Setup (see below)</b>
* Validate payment_request_hash matches SHA256 of the decrypted, serialized PaymentRequest
* Deserialize the serialized PaymentRequest

===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 the given InvoiceRequest's nonce field 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)

===Initial Public Key Retrieval for InvoiceRequest Encryption===
Initial public key retrieval for InvoiceRequest encryption can be done in a number of ways including, but not limited to, the following:
* Wallet Name public key asset type resolution - DNSSEC-validated name resolution returns Base64 encoded DER-formatted EC public key via TXT Record [https://www.ietf.org/rfc/rfc5480.txt RFC 5480]
* Key Server lookup - Key Server lookup (similar to PGP's pgp.mit.edu) based on key server identifier (i.e., e-mail address) returns Base64 encoded DER-formatted EC public key [https://www.ietf.org/rfc/rfc5480.txt RFC 5480]
* QR Code - Use of QR-code to encode DER-formatted EC public key [https://www.ietf.org/rfc/rfc5480.txt RFC 5480]

==Payment Messages with a Store & Foward Server==
When a Store & Forward server is in use during the Payment Protocol exchange, an EncryptedPayment message generated as the result of a 
received EncryptedPaymentRequest MUST be accepted by a Store & Forward server if the EncryptedPayment message is appropriately correlated
to an InvoiceRequest/PaymentRequest exchange. This correlation SHOULD be done in order to decrease spam requests. The accepted 
Payment message is NOT validated as the Store & Forward server does not have access to the original PaymentRequest.

Store & Forward servers MAY accept and/or overwrite EncryptedPayment messages until an EncryptedPaymentACK message with matching payment request hash and payee signature is received, after which the server MAY reject all further EncryptedPayment messages matching that payment request hash. This feature SHOULD be used for updating payment request metadata or replacing invalid transactions with valid ones; clients MUST NOT assume payment requests that have not received an ACK will not be broadcast to the Bitcoin network by the payee.


==Implementation==
A reference implementation for a Store & Forward server supporting this proposal can be found here: 

[https://github.com/netkicorp/addressimo Addressimo]

A reference client implementation can be found in the InvoiceRequest functional testing for Addressimo here: 

[https://github.com/netkicorp/addressimo/blob/master/functest/functest_ir.py InvoiceRequest Client Reference Implementation]

==BIP70 Extension==
The following flowchart is borrowed from BIP70 and expanded upon in order to visually describe how this BIP is an extension to BIP70.

<img src="bip-ir/bip70-extension.png"></img>

==Mobile to Mobile Example==
The following diagram shows a sample flow in which one mobile client is sending value to a second mobile client with the use
of an InvoiceRequest, a Store & Forward server, and a EncryptedPaymentRequest.

<img src="bip-ir/mobile-sf-bip70-extension.png"></img>

==References==

* [[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]
* [https://en.bitcoin.it/wiki/Address_reuse Address Reuse]