Skip to content

Commit ad3a16b

Browse files
luke-jrluke-jr
authored
Merge pull request bitcoin#725 from kallewoof/bip-generic-signmessage
BIP 322: Generic Signed Message Format
2 parents 43f59df + 2f15277 commit ad3a16b

File tree

2 files changed

+176
-0
lines changed

2 files changed

+176
-0
lines changed

‎README.mediawiki

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -840,6 +840,13 @@ Those proposing changes should consider that ultimately consent may rest with th
840840
| BtcDrak
841841
| Standard
842842
| Draft
843+
|-
844+
| [[bip-0322.mediawiki|322]]
845+
| Applications
846+
| Generic Signed Message Format
847+
| Karl-Johan Alm
848+
| Standard
849+
| Draft
843850
|}
844851

845852
<!-- IMPORTANT! See the instructions at the top of this page, do NOT JUST add BIPs here! -->

‎bip-0322.mediawiki

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
<pre>
2+
BIP: 322
3+
Layer: Applications
4+
Title: Generic Signed Message Format
5+
Author: Karl-Johan Alm <[email protected]>
6+
Comments-Summary: No comments yet.
7+
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0322
8+
Status: Draft
9+
Type: Standards Track
10+
Created: 2018-09-10
11+
License: CC0-1.0
12+
</pre>
13+
14+
== Abstract ==
15+
16+
A standard for interoperable generic signed messages based on the Bitcoin Script format.
17+
18+
== Motivation ==
19+
20+
The current message signing standard only works for P2PKH (1...) addresses. By extending it to use a Bitcoin Script based approach, it could be made more generic without causing a too big burden on implementers, who most likely have access to Bitcoin Script interpreters already.
21+
22+
== Specification ==
23+
24+
A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.
25+
26+
Two actions "Sign" and "Verify" are defined along with two *purposes* "SignMessage" and "ProveFunds".
27+
28+
=== SignatureProof container ===
29+
30+
{|class="wikitable" style="text-align: center;"
31+
|-
32+
!Type
33+
!Length
34+
!Name
35+
!Comment
36+
|-
37+
|Uint32||4||flags||standard flags (1-to-1 with standard flags in Bitcoin Core)
38+
|-
39+
|VarInt||1-8||msglen||Number of bytes in message string, excluding NUL termination
40+
|-
41+
|Char*||[msglen]||msg||The message being signed for all subjects, excluding NUL termination
42+
|-
43+
|Uint8||1||entries||Number of proof entries<ref><strong>Why support multiple proofs?</strong> In particular with proof of funds, it is non-trivial to check a large number of individual proofs (one per UTXO) for duplicates. Software could be written to do so, but it seems more efficient to build this check into the specification itself.</ref>
44+
|}
45+
46+
The above is followed by [entries] number of signature entries:
47+
48+
{|class="wikitable" style="text-align: center;"
49+
|-
50+
!Type
51+
!Length
52+
!Name
53+
!Comment
54+
|-
55+
|VarInt||1-8||scriptsiglen||Number of bytes in scriptSig data
56+
|-
57+
|Uint8*||[scriptsiglen]||scriptsig||ScriptSig data
58+
|-
59+
|VarInt||1-8||witlen||Number of bytes in witness data
60+
|-
61+
|Uint8*||[witlen]||wit||Witness
62+
|}
63+
64+
In some cases, the scriptsig or wit may be empty. If both are empty, the proof is incomplete.
65+
66+
=== Result Codes ===
67+
68+
A verification call will return a result code according to the table below.
69+
70+
{|class="wikitable" style="text-align: center;"
71+
|-
72+
!Code
73+
!Description
74+
|-
75+
|INCOMPLETE||One or several of the given challenges had an empty proof. The prover may need some other entity to complete the proof.
76+
|-
77+
|INCONCLUSIVE||One or several of the given proofs used unknown opcodes or the scriptPubKey had an unknown witness version, perhaps due to the verifying node being outdated.
78+
|-
79+
|VALID||All proofs were deemed valid.
80+
|-
81+
|INVALID||One or more of the given proofs were invalid
82+
|-
83+
|SPENT||One or more of the claimed UTXO:s has been spent
84+
|-
85+
|ERROR||An error was encountered
86+
|}
87+
88+
== Signing and Verifying ==
89+
90+
Let there be an empty set `inputs` which is populated and tested at each call to one of the actions below.
91+
92+
=== Purpose: SignMessage ===
93+
94+
The "SignMessage" purpose generates a sighash based on a scriptPubKey and a message. It emits a VALID verification result code unless otherwise stated.
95+
96+
# Return INVALID if scriptPubKey already exists in `inputs` set, otherwise insert it<ref><strong>Why track duplicates?</strong> Because a 3-entry proof is not proving 3 inputs unless they are all distinct</ref>
97+
# Define the message pre-image as the sequence "Bitcoin Message:" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD)
98+
# Let sighash = sha256(sha256(scriptPubKey || pre-image))
99+
100+
=== Purpose: ProveFunds ===
101+
102+
The "ProveFunds" purpose generates a sighash and a scriptPubKey from a transaction, an output index, and a message. For multiple simultaneous proofs, it also requires access to the ordered list of proofs. It emits a VALID verification result code unless otherwise stated.
103+
104+
# Let txid be the transaction ID of the transaction, and vout be the output index corresponding to the index of the output being spent
105+
# Return INVALID if the txid:vout pair already exists in `inputs` set, otherwise insert it
106+
# Return SPENT if the txid/vout is not a valid UTXO according to a Bitcoin node<ref><strong>Synced up or not?</strong> A normal verifier would use a synced up node. An auditor checking records from a client that were submitted in the past want to use a node that is synced up to the block corresponding to the proof, or the proof will fail, even if it may have been valid at the time of creation.</ref>
107+
# Extract scriptPubKey from transaction output
108+
# Define the message pre-image as the concatenation of the following components:<ref><strong>Why not just the UTXO data?</strong> We want the verifier to be able to challenge the prover with a custom message to sign, or anyone can reuse the POF proof for a set of UTXO:s once they have seen it, and the funds have not yet been spent</ref>
109+
#* the string "POF:"
110+
#* the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD), including the null terminating character (i.e. write strlen(message) + 1 bytes, for a C string)
111+
#* all transactions being proven for, as binary txid (little endian uint256) followed by index (little endian uint32), each separated by a single `0x00` byte
112+
# Let sighash = sha256(sha256(scriptPubKey || pre-image))
113+
114+
=== Action: Sign ===
115+
116+
The "Sign" action takes as input a purpose. It returns a signature or fails.
117+
118+
# Obtain the sighash and scriptPubKey from the purpose; FAIL if not VALID
119+
# Derive the private key privkey for the scriptPubKey; FAIL if not VALID
120+
# Generate and return a signature sig with privkey=privkey, sighash=sighash
121+
122+
=== Action: Verify ===
123+
124+
The "Verify" action takes as input a standard flags value, a script sig, an optional witness, and a purpose.
125+
It emits one of INCONCLUSIVE, VALID, INVALID, or ERROR.
126+
127+
# Obtain the sighash and scriptPubKey from the purpose; pass on result code if not VALID
128+
# If one or more of the standard flags are unknown, return INCONCLUSIVE
129+
# Verify Script with flags=standard flags, scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
130+
# Return VALID if verify succeeds, otherwise return INVALID
131+
132+
=== Multiple Proofs ===
133+
134+
When more than one proof is created or verified, repeat the operation for each proof, retaining the inputs set. As noted, if the same input appears more than once, the operation must fail accordingly.
135+
136+
Note that the order of the entries in the proof must match the order of the entries given by the verifier.
137+
138+
* If any of the proofs are empty during a verification process, skip the verification and set the INCOMPLETE flag
139+
* If a verification call returns ERROR or INVALID, return ERROR or INVALID immediately, ignoring as yet unverified entries
140+
* After all verifications complete,
141+
** return INCONCLUSIVE if any verification call returned INCONCLUSIVE
142+
** return SPENT if any verification call returned SPENT
143+
** return INCOMPLETE if the INCOMPLETE flag is set
144+
** return VALID
145+
146+
== Compatibility ==
147+
148+
This specification is not backwards compatible with the legacy signmessage/verifymessage specification. However, legacy addresses (1...) may be used in this implementation without any problems.
149+
150+
== Rationale ==
151+
152+
<references/>
153+
154+
== Reference implementation ==
155+
156+
To do.
157+
158+
== Acknowledgements ==
159+
160+
TODO
161+
162+
== References ==
163+
164+
# Original mailing list thread: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-March/015818.html
165+
# Pull request, with comments: https://github.com/bitcoin/bips/pull/725
166+
167+
== Copyright ==
168+
169+
This document is licensed under the Creative Commons CC0 1.0 Universal license.

0 commit comments

Comments
 (0)