bitcoin/bips
1
0
Fork 0
mirror of https://github.com/bitcoin/bips.git synced 2026-07-06 17:46:00 +00:00
Code Issues Releases Wiki Activity

Fix other broken anchors

Browse Source 
Used the following `sed` command and manually verified the unstaged
changes. Special cases that were not committed included external links
to Wikipedia which are case-sensitive, links specific lines in code, a
link to a title with a slash that had to be cleaned up, and links to
citations on the BIP repository that contain an underscore.

```
sed -E -i '
s/(\[\[[^][]*#)([^]|]*)(\||\]\])/\1\L\2\E\3/g
:again
s/(\[\[[^][]*#)([^]|]*)([: _]+)([^]|]*)(\||\]\])/\1\2-\4\5/g
t again
' bip-0*mediawiki
```
This commit is contained in:
Murch
2026-02-27 14:12:41 -08:00
parent 32b7adf847
commit b3a069464a
14 changed files with 46 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
bip-0075.mediawiki
View File

@@ -125,13 +125,13 @@ message InvoiceRequest {
|-
| memo || Human-readable description of invoice request for the receiver
|-
| notification_url || Secure (usually TLS-protected HTTP) location where an [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] SHOULD be sent when ready
| notification_url || Secure (usually TLS-protected HTTP) location where an [[#encryptedprotocolmessage|EncryptedProtocolMessage]] SHOULD be sent when ready
|-
| signature || PKI-dependent signature
|}
===ProtocolMessageType Enum===
This enum is used in the newly defined [[#ProtocolMessage|ProtocolMessage]] and [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] messages to define the serialized message type. The '''ProtocolMessageType''' enum is defined in an extensible way to allow for new message type additions to the Payment Protocol.
This enum is used in the newly defined [[#protocolmessage|ProtocolMessage]] and [[#encryptedprotocolmessage|EncryptedProtocolMessage]] messages to define the serialized message type. The '''ProtocolMessageType''' enum is defined in an extensible way to allow for new message type additions to the Payment Protocol.
<pre>
enum ProtocolMessageType {
UNKNOWN_MESSAGE_TYPE = 0;
@@ -219,12 +219,12 @@ message EncryptedProtocolMessage {
==Payment Protocol Process with InvoiceRequests==
The full process overview for using '''InvoiceRequests''' in the Payment Protocol is defined below.
<br/><br/>
All Payment Protocol messages MUST be encapsulated in either a [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProtocolMessage|EncryptedProtocolMessage]]. Once the process begins using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] messages, all subsequent communications MUST use [[#EncryptedProtocolMessage|EncryptedProtocolMessages]].
All Payment Protocol messages MUST be encapsulated in either a [[#protocolmessage|ProtocolMessage]] or [[#encryptedprotocolmessage|EncryptedProtocolMessage]]. Once the process begins using [[#encryptedprotocolmessage|EncryptedProtocolMessage]] messages, all subsequent communications MUST use [[#encryptedprotocolmessage|EncryptedProtocolMessages]].
<br/><br/>
All Payment Protocol messages SHOULD be communicated using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] encapsulating messages with the exception that an [[#InvoiceRequest|InvoiceRequest]] MAY be communicated using the [[#ProtocolMessage|ProtocolMessage]] if the receiver's public key is unknown.
All Payment Protocol messages SHOULD be communicated using [[#encryptedprotocolmessage|EncryptedProtocolMessage]] encapsulating messages with the exception that an [[#invoicerequest|InvoiceRequest]] MAY be communicated using the [[#protocolmessage|ProtocolMessage]] if the receiver's public key is unknown.
<br/><br/>
The process of creating encrypted Payment Protocol messages is enumerated in [[#Sending_Encrypted_Payment_Protocol_Messages_using_EncryptedProtocolMessages|Sending Encrypted Payment Protocol Messages using EncryptedProtocolMessages]], and the process of decrypting encrypted messages can be found under [[#Validating_and_Decrypting_Payment_Protocol_Messages_using_EncryptedProtocolMessages|Validating and Decrypting Payment Protocol Messages using EncryptedProtocolMessages]].
The process of creating encrypted Payment Protocol messages is enumerated in [[#sending-encrypted-payment-protocol-messages-using-encryptedprotocolmessages|Sending Encrypted Payment Protocol Messages using EncryptedProtocolMessages]], and the process of decrypting encrypted messages can be found under [[#validating-and-decrypting-payment-protocol-messages-using-encryptedprotocolmessages|Validating and Decrypting Payment Protocol Messages using EncryptedProtocolMessages]].
A standard exchange from start to finish would look like the following:
@@ -238,7 +238,7 @@ A standard exchange from start to finish would look like the following:
# Sender validates PaymentRequest retrieved from the EncryptedProtocolMessage
# The PaymentRequest is processed according to [[bip-0070.mediawiki|BIP70]], including optional Payment and PaymentACK messages encapsulated in EncryptedProtocolMessage messages.
'''NOTE:''' See [[#Initial_Public_Key_Retrieval_for_InvoiceRequest_Encryption|Initial Public Key Retrieval for InvoiceRequest Encryption]] for possible options to retrieve Receiver's public key.
'''NOTE:''' See [[#initial-public-key-retrieval-for-invoicerequest-encryption|Initial Public Key Retrieval for InvoiceRequest Encryption]] for possible options to retrieve Receiver's public key.
<img src="bip-0075/encrypted-invoice-request-process.png" alt="Flow diagram of Encrypted InvoiceRequest">
@@ -257,7 +257,7 @@ When communicated via '''HTTP''', the listed messages MUST be transmitted via TL
===Payment Protocol Status Communication===
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.
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.
<br/><br/>
The status_message value SHOULD be set with a human readable explanation of the status code.
@@ -311,27 +311,27 @@ For the following we assume the Sender already knows the Receiver's public key,
'''nonce''' MUST be set to a non-repeating number '''and''' MUST be chosen by the encryptor. 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). The service receiving the message containing the '''nonce''' MAY use whatever method to make sure that the '''nonce''' is never repeated.
===InvoiceRequest Message Creation===
* Create an [[#InvoiceRequest|InvoiceRequest]] message
* Create an [[#invoicerequest|InvoiceRequest]] message
* '''sender_public_key''' MUST be set to the public key of an EC keypair
* '''amount''' is optional. If the amount is not specified by the [[#InvoiceRequest|InvoiceRequest]], the Receiver MAY specify the amount in the returned PaymentRequest. If an amount is specified by the [[#InvoiceRequest|InvoiceRequest]] and a PaymentRequest cannot be generated for that amount, the [[#InvoiceRequest|InvoiceRequest]] SHOULD return the same [[#InvoiceRequest|InvoiceRequest]] in a [[#ProtocolMessage|ProtocolMessage]] or [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] with the status_code and status_message fields set appropriately.
* '''amount''' is optional. If the amount is not specified by the [[#invoicerequest|InvoiceRequest]], the Receiver MAY specify the amount in the returned PaymentRequest. If an amount is specified by the [[#invoicerequest|InvoiceRequest]] and a PaymentRequest cannot be generated for that amount, the [[#invoicerequest|InvoiceRequest]] SHOULD return the same [[#invoicerequest|InvoiceRequest]] in a [[#protocolmessage|ProtocolMessage]] or [[#encryptedprotocolmessage|EncryptedProtocolMessage]] with the status_code and status_message fields set appropriately.
* '''memo''' is optional. This MAY be set to a human readable description of the InvoiceRequest
* Set '''notification_url''' to URL that the Receiver will submit completed PaymentRequest (encapsulated in an [[#EncryptedProtocolMessage|EncryptedProtocolMessage]]) to
* Set '''notification_url''' to URL that the Receiver will submit completed PaymentRequest (encapsulated in an [[#encryptedprotocolmessage|EncryptedProtocolMessage]]) 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 ([https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#Certificates Certificates])
** Sign [[#InvoiceRequest|InvoiceRequest]] with signature = "" using the X509 Certificate's private key
** Sign [[#invoicerequest|InvoiceRequest]] with signature = "" using the X509 Certificate's private key
** Set '''signature''' value to the computed signature
===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|InvoiceRequest]] is VALID
* If '''pki_type''' is x509+sha256 and '''signature''' is valid for the serialized [[#InvoiceRequest|InvoiceRequest]] where signature is set to "", [[#InvoiceRequest|InvoiceRequest]] is VALID
* If '''pki_type''' is None, [[#invoicerequest|InvoiceRequest]] is VALID
* If '''pki_type''' is x509+sha256 and '''signature''' is valid for the serialized [[#invoicerequest|InvoiceRequest]] where signature is set to "", [[#invoicerequest|InvoiceRequest]] is VALID
===Sending Encrypted Payment Protocol Messages using EncryptedProtocolMessages===
* Encrypt the serialized Payment Protocol message using AES-256-GCM setup as described in [[#ECDH_Point_Generation_and_AES256_GCM_Mode_Setup|ECDH Point Generation and AES-256 (GCM Mode) Setup]]
* Create [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] message
* Encrypt the serialized Payment Protocol message using AES-256-GCM setup as described in [[#ecdh-point-generation-and-aes256-gcm-mode-setup|ECDH Point Generation and AES-256 (GCM Mode) Setup]]
* Create [[#encryptedprotocolmessage|EncryptedProtocolMessage]] message
* Set '''encrypted_message''' to be the encrypted value of the Payment Protocol message
* '''version''' SHOULD be set to the highest version number the client understands (currently 1)
* '''sender_public_key''' MUST be set to the public key of the Sender's EC keypair
@@ -339,14 +339,14 @@ For the following we assume the Sender already knows the Receiver's public key,
* '''nonce''' MUST be set to the nonce used in the AES-256-GCM encryption operation
* Set '''identifier''' to the identifier value received in the originating InvoiceRequest's ProtocolMessage or EncryptedProtocolMessage wrapper message
* Set '''signature''' to ""
* Sign the serialized [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] message with the communicating party's EC public key
* Sign the serialized [[#encryptedprotocolmessage|EncryptedProtocolMessage]] message with the communicating party's EC public key
* Set '''signature''' to the result of the signature operation above
'''SIGNATURE NOTE:''' [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] messages are signed with the public keys of the party transmitting the message. This allows a Store & Forward server or other transmission system to prevent spam or other abuses. For those who are privacy conscious and don't want the server to track the interactions between two public keys, the Sender can generate a new public key for each interaction to keep their identity anonymous.
'''SIGNATURE NOTE:''' [[#encryptedprotocolmessage|EncryptedProtocolMessage]] messages are signed with the public keys of the party transmitting the message. This allows a Store & Forward server or other transmission system to prevent spam or other abuses. For those who are privacy conscious and don't want the server to track the interactions between two public keys, the Sender can generate a new public key for each interaction to keep their identity anonymous.
===Validating and Decrypting Payment Protocol Messages using EncryptedProtocolMessages===
* The '''nonce''' MUST not be repeated. The service receiving the [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] MAY use whatever method to make sure that the nonce is never repeated.
* Decrypt the serialized Payment Protocol message using AES-256-GCM setup as described in [[#ECDH_Point_Generation_and_AES256_GCM_Mode_Setup|ECDH Point Generation and AES-256 (GCM Mode) Setup]]
* The '''nonce''' MUST not be repeated. The service receiving the [[#encryptedprotocolmessage|EncryptedProtocolMessage]] MAY use whatever method to make sure that the nonce is never repeated.
* Decrypt the serialized Payment Protocol message using AES-256-GCM setup as described in [[#ecdh-point-generation-and-aes256-gcm-mode-setup|ECDH Point Generation and AES-256 (GCM Mode) Setup]]
* Deserialize the serialized Payment Protocol message
===ECDH Point Generation and AES-256 (GCM Mode) Setup===
@@ -369,7 +369,7 @@ The 16 byte authentication tag resulting from the AES-GCM encrypt operation MUST
When either '''status_code''' OR '''status_message''' are present, the AES-256 GCM authenticated data used in both the encrypt and decrypt operations MUST be: STRING(status_code) || status_message. Otherwise, there is no additional authenticated data. This provides that, while not encrypted, the status_code and status_message are authenticated.
===Initial Public Key Retrieval for InvoiceRequest Encryption===
Initial public key retrieval for [[#InvoiceRequest|InvoiceRequest]] encryption via [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] encapsulation can be done in a number of ways including, but not limited to, the following:
Initial public key retrieval for [[#invoicerequest|InvoiceRequest]] encryption via [[#encryptedprotocolmessage|EncryptedProtocolMessage]] encapsulation 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 SEC-formatted EC public key [https://www.ietf.org/rfc/rfc5480.txt RFC 5480]
@@ -408,12 +408,12 @@ The following flowchart is borrowed from [[bip-0070.mediawiki|BIP70]] and expand
==Mobile to Mobile Examples==
===Full Payment Protocol===
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, PaymentRequest, Payment and PaymentACK. In this case, the PaymentRequest, Payment and PaymentACK messages are encrypted using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] '''and''' the Receiver submits the transaction to the Bitcoin network.
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, PaymentRequest, Payment and PaymentACK. In this case, the PaymentRequest, Payment and PaymentACK messages are encrypted using [[#encryptedprotocolmessage|EncryptedProtocolMessage]] '''and''' the Receiver submits the transaction to the Bitcoin network.
<img src="bip-0075/mobile-sf-ir-with-payment.png" alt="Payment Required flow diagram">
===Encrypting Initial InvoiceRequest via EncryptedProtocolMessage===
The following diagram shows a sample flow in which one mobile client is sending value to a second mobile client using an [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] to transmit the InvoiceRequest using encryption, Store & Forward server, and PaymentRequest. In this case, all Payment Protocol messages are encrypting using [[#EncryptedProtocolMessage|EncryptedProtocolMessage]] '''and''' the Sender submits the transaction to the Bitcoin network.
The following diagram shows a sample flow in which one mobile client is sending value to a second mobile client using an [[#encryptedprotocolmessage|EncryptedProtocolMessage]] to transmit the InvoiceRequest using encryption, Store & Forward server, and PaymentRequest. In this case, all Payment Protocol messages are encrypting using [[#encryptedprotocolmessage|EncryptedProtocolMessage]] '''and''' the Sender submits the transaction to the Bitcoin network.
<img src="bip-0075/mobile-sf-encrypted-ir-without-payment.png" alt="Encrypted InvoiceRequest without payment">