Difference between revisions of "BIP 0322"
(Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip0322.mediawiki) 
(Update BIP text with latest version from https://github.com/bitcoin/bips/blob/c134a853a9fc0657/bip0322.mediawiki) 

Line 37:  Line 37:  
A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.  A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.  
−  
−  
=== SignatureProof container ===  === SignatureProof container ===  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
{class="wikitable" style="textalign: center;"  {class="wikitable" style="textalign: center;"  
Line 83:  Line 67:  
!Description  !Description  
    
−  INCOMPLETE  +  INCOMPLETEEmpty proof. 
    
−  INCONCLUSIVE  +  INCONCLUSIVEThe given proof was consensusvalid but policyinvalid. 
    
−  VALID  +  VALIDThe proof was valid. 
    
−  INVALID  +  INVALIDThe proof was invalid 
    
ERRORAn error was encountered  ERRORAn error was encountered  
Line 96:  Line 80:  
== Signing and Verifying ==  == Signing and Verifying ==  
−  If the challenge consists of  +  If the challenge consists of an address is in the P2PKH (legacy) format, sign using the legacy format (further information below). Otherwise continue as stated below. 
−  
−  
−  +  For both cases, generate a sighash based on the given scriptPubKey and message as follows:  
−  
−  
−  
# Define the message preimage as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF8 using Normalization Form Compatibility Decomposition (NFKD)  # Define the message preimage as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF8 using Normalization Form Compatibility Decomposition (NFKD)  
# Let sighash = sha256(sha256(scriptPubKey  preimage))  # Let sighash = sha256(sha256(scriptPubKey  preimage))  
Line 110:  Line 89:  
A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.  A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.  
−  ===  +  === Signing === 
−  The  +  The signature is generated as follows: 
−  
# Derive the private key privkey for the scriptPubKey; FAIL if not VALID  # Derive the private key privkey for the scriptPubKey; FAIL if not VALID  
# Generate and return a signature sig with privkey=privkey, sighash=sighash  # Generate and return a signature sig with privkey=privkey, sighash=sighash  
−  +  === Verifying ===  
−  +  Verify a proof, given a standard flags value, a script sig, an optional witness, and a derived sighash as described above.  
−  
−  
−  
While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a nonlegacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.  While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a nonlegacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.  
−  
# Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash  # Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash  
# Return INVALID if verification fails  # Return INVALID if verification fails  
# Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash  # Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash  
# Return VALID if verification succeeds, otherwise return INCONCLUSIVE  # Return VALID if verification succeeds, otherwise return INCONCLUSIVE  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
−  
== Legacy format ==  == Legacy format ==  
−  The legacy format is restricted to the legacy P2PKH address format  +  The legacy format is restricted to the legacy P2PKH address format. 
−  Any other input (e.  +  Any other input (i.e. nonP2PKH address format) must be signed using the new format described above. 
=== Signing ===  === Signing ===  
Line 177:  Line 138:  
This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.  This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.  
−  
−  
−  
−  
== Reference implementation ==  == Reference implementation ==  
Line 231:  Line 188:  
== Test vectors ==  == Test vectors ==  
+  
+  (TODO: update test vectors, which are based on previous iteration where signature proofs contained additional data)  
== Native segwit test vector ==  == Native segwit test vector == 
Latest revision as of 07:36, 2 August 2020
This page describes a BIP (Bitcoin Improvement Proposal). 
Please do not modify this page. This is a mirror of the BIP from the source Git repository here. 
BIP: 322 Layer: Applications Title: Generic Signed Message Format Author: KarlJohan Alm <karljohanalm@garage.co.jp> CommentsSummary: No comments yet. CommentsURI: https://github.com/bitcoin/bips/wiki/Comments:BIP0322 Status: Draft Type: Standards Track Created: 20180910 License: CC01.0
Contents
Abstract
A standard for interoperable generic signed messages based on the Bitcoin Script format.
Background
 Assume two actors, a prover
P
and a verifierV
. 
P
wants to prove that they own the private keyk
associated with a given addressA
(which in turn is derived from the pubkeykG
).  Let
V
generate a messageM
and hand this toP
. 
P
generates a signatureS
by signing the messageM
usingk
. GivenS
,V
can prove thatP
has the private key associated withA
.
The astute reader will notice that the above is missing a critical part, namely the pubkey kG
, without which the verifier cannot actually verify the message. The current message signing standard solves this via a cryptographic trick, wherein the signature S
above is a special "recoverable signature" type. Given the message M
and the signature S
, it is then possible to recover the pubkey kG
. The system thus derives the address for the pubkey kG
, and if it does not match A
, the proof is deemed invalid.
While this is a neat trick, it unnecessarily restricts and complicates the message signing mechanism; for instance, it is currently not possible to sign a message for a P2SH address, because there is no pubkey to recover from the resulting signature.
Motivation
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.
Specification
A new structure SignatureProof
is added, which is a simple serializable scriptSig & witness container.
SignatureProof container
Type  Length  Name  Comment 

VarInt  18  scriptsiglen  Number of bytes in scriptSig data 
Uint8*  [scriptsiglen]  scriptsig  ScriptSig data 
VarInt  18  witlen  Number of entries in witness stack 
Uint8[]*  [witlen]  wit  Witness stack, as [witlen] uint8* vectors, each one prepended with a varint of its size 
In some cases, the scriptsig or wit may be empty. If both are empty, the proof is incomplete.
Result Codes
A verification call will return a result code according to the table below.
Code  Description 

INCOMPLETE  Empty proof. 
INCONCLUSIVE  The given proof was consensusvalid but policyinvalid. 
VALID  The proof was valid. 
INVALID  The proof was invalid 
ERROR  An error was encountered 
Signing and Verifying
If the challenge consists of an address is in the P2PKH (legacy) format, sign using the legacy format (further information below). Otherwise continue as stated below.
For both cases, generate a sighash based on the given scriptPubKey and message as follows:
 Define the message preimage as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF8 using Normalization Form Compatibility Decomposition (NFKD)
 Let sighash = sha256(sha256(scriptPubKey  preimage))
A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.
Signing
The signature is generated as follows:
 Derive the private key privkey for the scriptPubKey; FAIL if not VALID
 Generate and return a signature sig with privkey=privkey, sighash=sighash
Verifying
Verify a proof, given a standard flags value, a script sig, an optional witness, and a derived sighash as described above.
While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a nonlegacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.
 Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
 Return INVALID if verification fails
 Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
 Return VALID if verification succeeds, otherwise return INCONCLUSIVE
Legacy format
The legacy format is restricted to the legacy P2PKH address format.
Any other input (i.e. nonP2PKH address format) must be signed using the new format described above.
Signing
Given the P2PKH address a
and the message m
, and the pubkeyhash function pkh(P) = ripemd160(sha256(P))
:
 let
p
be the pubkeyhashpkh(P)
for the pubkeyP
, contained ina
 let
x
be the private key associated withP
so thatpkh(xG) = p
 let
digest
beSHA56d("Bitcoin Signed Message:\n"m)
 create a compact signature
sig
(aka "recoverable ECDSA signature") usingx
ondigest
The resulting proof is sig
, serialized using the base64 encoding.
Verifying
Given the P2PKH address a
, the message m
, the compact signature sig
, and the pubkeyhash function pkh(P) = ripemd160(sha256(P))
:
 let
p
be the pubkeyhashpkh(P)
for the pubkeyP
, contained ina
 let
digest
beSHA56d("Bitcoin Signed Message:\n"m)
 attempt pubkey recovery for
digest
using the signaturesig
and store the resulting pubkey intoQ
 fail verification if pubkey recovery above fails
 let
q
be the pubkeyhashpkh(Q)
for the pubkeyQ
 if
p == q
, the proof is valid, otherwise it is invalid
Compatibility
This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.
Reference implementation
 Pull request to Bitcoin Core: https://github.com/bitcoin/bitcoin/pull/16440
Acknowledgements
Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, and many others for their feedback on the specification.
References
 Original mailing list thread: https://lists.linuxfoundation.org/pipermail/bitcoindev/2018March/015818.html
Copyright
This document is licensed under the Creative Commons CC0 1.0 Universal license.
Consensus and standard flags
Each flag is associated with some type of enforced rule (most often a soft fork). There are two sets of flags: consensus flags (which result in a block being rejected, if violated), and policy flags (which result in a transaction being accepted only if it is contained within an actual block, and rejected otherwise, if violated). The policy flags are a superset of the consensus flags.
BIP322 specifies that a proof that validates for both rulesets is valid, a proof that validates for consensus rules, but not for policy rules, is "inconclusive", and a proof that does not validate for consensus rules is "invalid" (regardless of policy rule validation).
The ruleset sometimes changes. This BIP does not intend to be complete, nor does it indicate enforcement of rules, it simply lists the rules as they stand at the point of writing.
Consensus rules
 P2SH: evaluate P2SH (BIP16) subscripts
 DERSIG: enforce strict DER (BIP66) compliance
 NULLDUMMY: enforce NULLDUMMY (BIP147)
 CHECKLOCKTIMEVERIFY: enable CHECKLOCKTIMEVERIFY (BIP65)
 CHECKSEQUENCEVERIFY: enable CHECKSEQUENCEVERIFY (BIP112)
 WITNESS: enable WITNESS (BIP141)
Policy rules
All of the above, plus (subject to change):
 STRICTENC: nonstrict DER signature or undefined hashtype
 MINIMALDATA: require minimal encodings for all push operations
 DISCOURAGE_UPGRADABLE_NOPS: discourage use of NOPs reserved for upgrades
 CLEANSTACK: require that only a single stack element remains after evaluation
 MINIMALIF: Segwit script only: require the argument of OP_IF/NOTIF to be exactly 0x01 or empty vector
 NULLFAIL: signature(s) must be empty vector if a CHECK(MULTI)SIG operation failed
 LOW_S: signature with S > order/2 in a checksig operation
 DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM: v116 witness programs are nonstandard (i.e. forbidden)
 WITNESS_PUBKEYTYPE: public keys in segregated witness scripts must be compressed
 CONST_SCRIPTCODE: OP_CODESEPARATOR and FindAndDelete fail any nonsegwit scripts
Test vectors
(TODO: update test vectors, which are based on previous iteration where signature proofs contained additional data)
Native segwit test vector
address = bcrt1qe7nte4zk4ayly5tc53dtdjupgkz0lr8azx3rzz scriptpubkey = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd message = hello preimage = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd426974636f696e205369 676e6564204d6573736167653a0a68656c6c6f (scriptpubkey  "Bitcoin Signed Message:\nhello") sighash = 790eef86c204f0bff969ff822121317aa34eff0215dbd30ccf031e7b2f3f0cc1 (sha256d(preimage), displayed in bigendian)
The proof becomes:
HEX: 01000000010002473044022075b4fb40421d55c55462879cb352a85eeb3af2138d3f0290 2c9143f12870f5f70220119c2995c1661138142f3899c1fd6d1af7e790e0e081be72db9c e7bf5b5b932901210290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e7c1dee9e a6e2dcd869 Base64: AQAAAAEAAkcwRAIgdbT7QEIdVcVUYoecs1KoXus68hONPwKQLJFD8Shw9fcCIBGcKZXBZhE4 FC84mcH9bRr355Dg4IG+ctuc579bW5MpASECkL7M0Ctz7KV0Z7K28eRxYam3al5nWG58He6e puLc2Gk=
Split into components:
Type  Length  Name  Value  Comment 

Uint32  4  flags  01000000 
proof format version 
Uint8  1  entries  01 
1 entry 
VarInt  18  scriptsiglen  00 
0 byte scriptsig 
VarInt  18  wit entries  02 
2 witness stack entries 
VarInt  18  entry1len  47 
71 byte entry 
Uint8[71]  71  entry1  3044022075b4fb40421d55c55462879cb352a85eeb3af213
 
VarInt  18  entry2len  21 
33 byte entry 
Uint8[33]  33  entry2  0290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e

The above test vector is for a bech32 P2WPKH (native segwit) address. (Once BIP solidifies, will add test vector for other types.)