Skip to content

Commit ac8a5f4

Browse files
jmacwhytejmacwhyte
committed
Added versioning, canceling
1 parent c7fdd9d commit ac8a5f4

File tree

2 files changed

+64
-44
lines changed

2 files changed

+64
-44
lines changed

‎bip-0075.mediawiki

Lines changed: 42 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -136,46 +136,59 @@ enum ProtocolMessageType {
136136
The '''ProtocolMessage''' message is an encapsulating wrapper for any Payment Protocol message. It allows two-way, non-encrypted communication of Payment Protocol messages. The message also includes a status code and a status message that is used for error communication such that the protocol does not rely on transport-layer error handling.
137137
<pre>
138138
message ProtocolMessage {
139-
required ProtocolMessageType message_type = 1;
140-
required bytes serialized_message = 2;
141-
optional uint64 status_code = 3;
142-
optional string status_message = 4;
143-
optional bytes identifier = 5;
139+
required uint64 version = 1
140+
required uint64 status_code = 2;
141+
required ProtocolMessageType message_type = 3;
142+
required bytes serialized_message = 4;
143+
optional string status_message = 5;
144+
optional bytes identifier = 6;
144145
}
145146
</pre>
146147

147148
{| class="wikitable"
148149
! Field Name !! Description
149150
|-
151+
|version || Protocol version number (Currently 1)
152+
|-
153+
|status_code || Payment Protocol Status Code
154+
|-
150155
|message_type || Message Type of serialized_message
151156
|-
152157
|serialized_message || Serialized Payment Protocol Message
153158
|-
154-
|status_code || Payment Protocol Status Code
155-
|-
156159
|status_message || Human-readable Payment Protocol status message
157160
|-
158161
|identifier || Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
159162
|}
160163

164+
===Versioning===
165+
This BIP introduces version 1 of this protocol. All messages sent using these base requirements MUST use a value of 1 for the version number. Any future BIPs that modify this protocol (encryption schemes, etc) MUST each increment the version number by 1.
166+
167+
When initiating communication, the version field of the first message SHOULD be set to the highest verison number the sender understands. All clients MUST be able to understand all version numbers less than the highest number they support. If a client receives a message with a version number higher than they understand, they MUST send the message back to the sender with a status code of 101 ("version too high") and the version field set to the highest version number the recipient understands. The sender must then resend the original message using the same version number returned by the recipient or abort.
168+
161169
===EncryptedProtocolMessage===
162170
The '''EncryptedProtocolMessage''' message is an encapsualting wrapper for any Payment Protocol message. It allows two-way, authenticated and encrypted communication of Payment Protocol messages in order to keep their contents secret. The message also includes a status code and status message that is used for error communication such that the protocol does not rely on transport-layer error handling.
163171
<pre>
164172
message EncryptedProtocolMessage {
165-
required ProtocolMessageType message_type = 1;
166-
required bytes encrypted_message = 2;
167-
required bytes receiver_public_key = 3;
168-
required bytes sender_public_key = 4;
169-
required uint64 nonce = 5;
170-
optional bytes signature = 6;
171-
optional bytes identifier = 7;
172-
optional uint64 status_code = 8;
173+
required uint64 version = 1 [default = 1];
174+
required uint64 status_code = 2 [default = 1];
175+
required ProtocolMessageType message_type = 3;
176+
required bytes encrypted_message = 4;
177+
required bytes receiver_public_key = 5;
178+
required bytes sender_public_key = 6;
179+
required uint64 nonce = 7;
180+
optional bytes identifier = 8;
173181
optional string status_message = 9;
182+
optional bytes signature = 10;
174183
}
175184
</pre>
176185
{| class="wikitable"
177186
! Field Name !! Description
178187
|-
188+
| version || Protocol version number
189+
|-
190+
| status_code || Payment Protocol Status Code
191+
|-
179192
| message_type || Message Type of Decrypted encrypted_message
180193
|-
181194
| encrypted_message || AES-256-GCM Encrypted (as defined in BIP75) Payment Protocol Message
@@ -186,13 +199,11 @@ message EncryptedProtocolMessage {
186199
|-
187200
| nonce || Microseconds since epoch
188201
|-
189-
| signature || DER-encoded Signature over the full EncryptedProtocolMessage with EC Key Belonging to Sender / Receiver, respectively
190-
|-
191202
| identifier || Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
192203
|-
193-
| status_code || Payment Protocol Status Code
194-
|-
195204
| status_message || Human-readable Payment Protocol status message
205+
|-
206+
| signature || DER-encoded Signature over the full EncryptedProtocolMessage with EC Key Belonging to Sender / Receiver, respectively
196207
|}
197208

198209
==Payment Protocol Process with InvoiceRequests==
@@ -236,21 +247,25 @@ When communicated via '''HTTP''', the listed messages MUST be transmitted via TL
236247

237248
===Payment Protocol Status Communication===
238249

239-
In the case of an error that causes the Payment Protocol process to be stopped or requires that message be retried, a [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] MUST be returned by the party generating the error status_code. The content of the message MUST contain the same '''serialized_message''' or '''encrypted_message''' and identifier (if present) and MUST have the status_code set appropriately.
250+
Every [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] MUST include a status code which conveys information about the last message received, if any (for the first message sent, use a status of 1 "OK" even though there was no previous message). In the case of an error that causes the Payment Protocol process to be stopped or requires that message be retried, a ProtocolMessage or EncryptedProtocolMessage SHOULD be returned by the party generating the error. The content of the message MUST contain the same '''serialized_message''' or '''encrypted_message''' and identifier (if present) and MUST have the status_code set appropriately.
240251
<br/><br/>
241-
The status_message value SHOULD be set with a human readable explanation of the status code. For example, if in an [[#EncryptedProtocolMessage|EncryptedProtocolMessage]], the AES-256-GCM decryption fails to authenticate, an Authentication Failed (102) '''status_code''' MUST be returned to prevent oracle attacks.
252+
The status_message value SHOULD be set with a human readable explanation of the status code.
242253

243254
====Payment Protocol Status Codes====
244255
{| class="wikitable"
245256
! Status Code !! Description
246257
|-
247258
| 1 || OK
248259
|-
260+
| 2 || Cancel
261+
|-
249262
| 100 || General / Unknown Error
250263
|-
264+
| 101 || Version Too High
265+
|-
251266
| 102 || Authentication Failed
252267
|-
253-
| 102 || Encrypted Message Required
268+
| 103 || Encrypted Message Required
254269
|-
255270
| 200 || Amount Too High
256271
|-
@@ -272,8 +287,10 @@ The status_message value SHOULD be set with a human readable explanation of the
272287
|-
273288
|}
274289

275-
===Transport Layer Communication Errors===
290+
+==Canceling A Message==+
291+
If a participant to a transaction would like to inform the other party that a previous message should be canceled, they can send the same message with a status code of 2 ("Cancel") and, where applicable, an updated nonce. How recipients make use of the "Cancel" message is up to developers. For example, wallet developers may want to offer users the ability to cancel payment requests they have sent to other users, and have that change reflected in the recipient's UI. Developers using the non-encrypted ProtocolMessage may want to ignore "Cancel" messages, as it may be difficult to authenticate that the message originated from the same user.
276292

293+
===Transport Layer Communication Errors===
277294
Communication errors MUST be communicated to the party that initiated the communication via the communication layer's existing error messaging faciltiies. In the case of TLS-protected HTTP, this SHOULD be done through standard HTTP Status Code messaging ([https://tools.ietf.org/html/rfc7231 RFC 7231 Section 6]).
278295

279296
==Extended Payment Protocol Process Details==
@@ -306,6 +323,7 @@ For the following we assume the Sender already knows the Receiver's public key,
306323
* Encrypt the serialized Payment Protocol message using AES-256-CBC setup as described in [[#ECDH_Point_Generation_and_AES256_GCM_Mode_Setup|ECDH Point Generation and AES-256 (GCM Mode) Setup]]
307324
* Create [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] message
308325
* Set '''encrypted_message''' to be the encrypted value of the Payment Protocol message
326+
* '''version''' SHOULD be set to the highest version number the client understands (currently 1)
309327
* '''sender_public_key''' MUST be set to the public key of the Sender's EC keypair
310328
* '''receiver_public_key''' MUST be set to the public key of the Receiver's EC keypair
311329
* '''nonce''' MUST be set to the nonce used in the AES-256-CBC encryption operation
@@ -327,7 +345,7 @@ For the following we assume the Sender already knows the Receiver's public key,
327345
* 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
328346
* Initialize [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf HMAC_DRBG]
329347
** Use '''SHA512(secret point's X value in Big-Endian bytes)''' for Entropy
330-
** Use the given message's '''nonce''' field for Nonce
348+
** Use the given message's '''nonce''' field for Nonce, converted to byte string (Big Endian)
331349
332350
* Initialize AES-256 in GCM Mode
333351
** Initialize HMAC_DRBG with Security Strength of 256 bits

‎bip-0075/paymentrequest.proto

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -48,12 +48,12 @@ message PaymentACK {
4848
// BIP-IR Extensions
4949
message InvoiceRequest {
5050
required bytes sender_public_key = 1; // Sender's DER-Encoded EC Public Key
51-
optional uint64 amount = 3 [default = 0]; // amount is integer-number-of-satoshis
52-
optional string pki_type = 4 [default = "none"]; // none / x509+sha256
53-
optional bytes pki_data = 5; // Depends on pki_type
54-
optional string memo = 6; // Human-readable description of invoice request for the receiver
55-
optional string notification_url = 7; // URL to notify on EncryptedPaymentRequest ready
56-
optional bytes signature = 8; // PKI-dependent signature
51+
optional uint64 amount = 2 [default = 0]; // amount is integer-number-of-satoshis
52+
optional string pki_type = 3 [default = "none"]; // none / x509+sha256
53+
optional bytes pki_data = 4; // Depends on pki_type
54+
optional string memo = 5; // Human-readable description of invoice request for the receiver
55+
optional string notification_url = 6; // URL to notify on EncryptedPaymentRequest ready
56+
optional bytes signature = 7; // PKI-dependent signature
5757
}
5858

5959
enum ProtocolMessageType {
@@ -65,21 +65,23 @@ enum ProtocolMessageType {
6565
}
6666

6767
message ProtocolMessage {
68-
required ProtocolMessageType message_type = 1; // Message Type of serialized_message
69-
required bytes serialized_message = 2; // Serialized Payment Protocol Message
70-
optional uint64 status_code = 3; // Payment Protocol Status Code
71-
optional string status_message = 4; // Human-readable Payment Protocol status message
72-
optional bytes identifier = 5; // Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
68+
required uint64 version = 1 [default = 1]; // Protocol version number
69+
required uint64 status_code = 2 [default = 1]; // Payment Protocol Status Code (Default: 1 "OK")
70+
required ProtocolMessageType message_type = 3; // Message Type of serialized_message
71+
required bytes serialized_message = 4; // Serialized Payment Protocol Message
72+
optional string status_message = 5; // Human-readable Payment Protocol status message
73+
optional bytes identifier = 6; // Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
7374
}
7475

7576
message EncryptedProtocolMessage {
76-
required ProtocolMessageType message_type = 1; // Message Type of Decrypted encrypted_message
77-
required bytes encrypted_message = 2; // AES-256-GCM Encrypted (as defined in BIP75) Payment Protocol Message
78-
required bytes receiver_public_key = 3; // Receiver's DER-encoded EC Public Key
79-
required bytes sender_public_key = 4; // Sender's DER-encoded EC Public Key
80-
required uint64 nonce = 5; // Microseconds since epoch
81-
optional bytes signature = 6; // Signature over the full EncryptedProtocolMessage with EC Key Belonging to Sender / Receiver, respectively
82-
optional bytes identifier = 7; // Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
83-
optional uint64 status_code = 8; // Payment Protocol Status Code
84-
optional string status_message = 9; // Human-readable Payment Protocol status message
77+
required uint64 version = 1 [default = 1]; // Protocol version number
78+
required uint64 status_code = 2 [default = 1]; // Payment Protocol Status Code (Default: 1 "OK")
79+
required ProtocolMessageType message_type = 3; // Message Type of Decrypted encrypted_message
80+
required bytes encrypted_message = 4; // AES-256-GCM Encrypted (as defined in BIP75) Payment Protocol Message
81+
required bytes receiver_public_key = 5; // Receiver's DER-encoded EC Public Key
82+
required bytes sender_public_key = 6; // Sender's DER-encoded EC Public Key
83+
required uint64 nonce = 7; // Microseconds since epoch
84+
optional bytes identifier = 8; // Unique key to identify this entire exchange on the server. SHA256 of initial serialized InvoiceRequest SHOULD be used by default
85+
optional string status_message = 9; // Human-readable Payment Protocol status message
86+
optional bytes signature = 10; // Signature over the full EncryptedProtocolMessage with EC Key Belonging to Sender / Receiver, respectively
8587
}

0 commit comments

Comments
 (0)