BIP 0322: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
← Older edit
934 (talk | contribs)
Editors
882 edits
Update BIP text with latest version from https://github.com/bitcoin/bips/blob/c134a853a9fc0657/bip-0322.mediawiki
934 (talk | contribs)
Editors
882 edits
Update BIP text with latest version from https://github.com/bitcoin/bips/blob/70d9b07ab80ab3c2/bip-0322.mediawiki
 
(6 intermediate revisions by the same user not shown)
Line 17: Line 17:
== Abstract ==
== Abstract ==


A standard for interoperable generic signed messages based on the Bitcoin Script format.
A standard for interoperable signed messages based on the Bitcoin Script format, either for proving fund availability, or committing to a message as the intended recipient of funds sent to the invoice address.


== Background ==
== Motivation ==
 
The current message signing standard only works for P2PKH (1...) invoice addresses. We propose to extend and generalize the standard by using a Bitcoin Script based approach. This ensures that any coins, no matter what script they are controlled by, can in-principle be signed for. For easy interoperability with existing signing hardware, we also define a signature message format which resembles a Bitcoin transaction (except that it contains an invalid input, so it cannot be spent on any real network).
 
Additionally, the current message signature format uses ECDSA signatures which do not commit to the public key, meaning that they do not actually prove knowledge of any secret keys. (Indeed, valid signatures can be tweaked by 3rd parties to become valid signatures on certain related keys.)


* Assume two actors, a prover <code>P</code> and a verifier <code>V</code>.
Ultimately no message signing protocol can actually prove control of funds, both because a signature is obsolete as soon as it is created, and because the possessor of a secret key may be willing to sign messages on others' behalf even if it would not sign actual transactions. No signmessage protocol can fix these limitations.
* <code>P</code> wants to prove that they own the private key <code>k</code> associated with a given address <code>A</code> (which in turn is derived from the pubkey <code>kG</code>).
* Let <code>V</code> generate a message <code>M</code> and hand this to <code>P</code>.
* <code>P</code> generates a signature <code>S</code> by signing the message <code>M</code> using <code>k</code>. Given <code>S</code>, <code>V</code> can prove that <code>P</code> has the private key associated with <code>A</code>.


The astute reader will notice that the above is missing a critical part, namely the pubkey <code>kG</code>, without which the verifier cannot actually verify the message. The current message signing standard solves this via a cryptographic trick, wherein the signature <code>S</code> above is a special "recoverable signature" type. Given the message <code>M</code> and the signature <code>S</code>, it is then possible to recover the pubkey <code>kG</code>. The system thus derives the address for the pubkey <code>kG</code>, and if it does not match <code>A</code>, the proof is deemed invalid.
== Types of Signatures ==


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.
This BIP specifies three formats for signing messages: ''legacy'', ''simple'' and ''full''. Additionally, a variant of the ''full'' format can be used to demonstrate control over a set of UTXOs.


== Motivation ==
=== Legacy ===


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.
New proofs should use the new format for all invoice address formats, including P2PKH.


== Specification ==
The legacy format MAY be used, but must be restricted to the legacy P2PKH invoice address format.


A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.
=== Simple ===


=== SignatureProof container ===
A ''simple'' signature consists of a witness stack, consensus encoded as a vector of vectors of bytes, and base64-encoded. Validators should construct <code>to_spend</code> and <code>to_sign</code> as defined below, with default values for all fields except that


{|class="wikitable" style="text-align: center;"
* <code>message_hash</code> is a BIP340-tagged hash of the message, as specified below
|-
* <code>message_challenge</code> in <code>to_spend</code> is set to the scriptPubKey being signed with
!Type
* <code>message_signature</code> in <code>to_sign</code> is set to the provided simple signature.
!Length
!Name
!Comment
|-
|VarInt||1-8||scriptsiglen||Number of bytes in scriptSig data
|-
|Uint8*||[scriptsiglen]||scriptsig||ScriptSig data
|-
|VarInt||1-8||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.
and then proceed as they would for a full signature.


=== Result Codes ===
=== Full ===


A verification call will return a result code according to the table below.
Full signatures follow an analogous specification to the BIP-325 challenges and solutions used by Signet.


{|class="wikitable" style="text-align: center;"
Let there be two virtual transactions <code>to_spend</code> and <code>to_sign</code>.
|-
!Code
!Description
|-
|INCOMPLETE||Empty proof.
|-
|INCONCLUSIVE||The given proof was consensus-valid but policy-invalid.
|-
|VALID||The proof was valid.
|-
|INVALID||The proof was invalid
|-
|ERROR||An error was encountered
|}


== Signing and Verifying ==
The <code>to_spend</code> transaction is:


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.
    nVersion = 0
    nLockTime = 0
    vin[0].prevout.hash = 0000...000
    vin[0].prevout.n = 0xFFFFFFFF
    vin[0].nSequence = 0
    vin[0].scriptSig = OP_0 PUSH32[ message_hash ]
    vin[0].scriptWitness = []
    vout[0].nValue = 0
    vout[0].scriptPubKey = message_challenge


For both cases, generate a sighash based on the given scriptPubKey and message as follows:
where <code>message_hash</code> is a BIP340-tagged hash of the message, i.e. sha256_tag(m), where tag = <code>BIP0322-signed-message</code> and <code>m</code> is the message as is without length prefix or null terminator, and <code>message_challenge</code> is the to be proven (public) key script.


# Define the message pre-image as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD)
The <code>to_sign</code> transaction is:
# Let sighash = sha256(sha256(scriptPubKey || pre-image))


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.
    nVersion = 0 or (FULL format only) as appropriate (e.g. 2, for time locks)
    nLockTime = 0 or (FULL format only) as appropriate (for time locks)
    vin[0].prevout.hash = to_spend.txid
    vin[0].prevout.n = 0
    vin[0].nSequence = 0 or (FULL format only) as appropriate (for time locks)
    vin[0].scriptWitness = message_signature
    vout[0].nValue = 0
    vout[0].scriptPubKey = OP_RETURN


=== Signing ===
A full signature consists of the base64-encoding of the <code>to_sign</code> transaction in standard network serialisation once it has been signed.


The signature is generated as follows:
=== Full (Proof of Funds) ===


# Derive the private key privkey for the scriptPubKey; FAIL if not VALID
A signer may construct a proof of funds, demonstrating control of a set of UTXOs, by constructing a full signature as above, with the following modifications.
# Generate and return a signature sig with privkey=privkey, sighash=sighash


=== Verifying ===
* All outputs that the signer wishes to demonstrate control of are included as additional inputs of <code>to_sign</code>, and their witness and scriptSig data should be set as though these outputs were actually being spent.


Verify a proof, given a standard flags value, a script sig, an optional witness, and a derived sighash as described above.
Unlike an ordinary signature, validators of a proof of funds need access to the current UTXO set, to learn that the claimed inputs exist on the blockchain, and to learn their scriptPubKeys.


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 non-legacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.
== Detailed Specification ==


# Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
For all signature types, except legacy, the <code>to_spend</code> and <code>to_sign</code> transactions must be valid transactions which pass all consensus checks, except of course that the output with prevout <code>000...000:FFFFFFFF</code> does not exist.
# 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 ==
=== Verification ===


The legacy format is restricted to the legacy P2PKH address format.
A validator is given as input an address ''A'' (which may be omitted in a proof-of-funds), signature ''s'' and message ''m'', and outputs one of three states
* ''valid at time T and age S'' indicates that the signature has set timelocks but is otherwise valid
* ''inconclusive'' means the validator was unable to check the scripts
* ''invalid'' means that some check failed


Any other input (i.e. non-P2PKH address format) must be signed using the new format described above.
==== Verification Process ====


=== Signing ===
Validation consists of the following steps:


Given the P2PKH address <code>a</code> and the message <code>m</code>, and the pubkey-hash function <code>pkh(P) = ripemd160(sha256(P))</code>:
# Basic validation
## Compute the transaction <code>to_spend</code> from ''m'' and ''A''
## Decode ''s'' as the transaction <code>to_sign</code>
## If ''s'' was a full transaction, confirm all fields are set as specified above; in particular that
##* <code>to_sign</code> has at least one input and its first input spends the output of </code>to_spend</code>
##* <code>to_sign</code> has exactly one output, as specified above
## Confirm that the two transactions together satisfy all consensus rules, except for <code>to_spend</code>'s missing input, and except that ''nSequence'' of <code>to_sign</code>'s first input and ''nLockTime'' of <code>to_sign</code> are not checked.
# (Optional) If the validator does not have a full script interpreter, it should check that it understands all scripts being satisfied. If not, it should stop here and output ''inconclusive''.
# Check the **required rules**:
## All signatures must use the SIGHASH_ALL flag.
## The use of <code>CODESEPARATOR</code> or <code>FindAndDelete</code> is forbidden.
## <code>LOW_S</code>, <code>STRICTENC</code> and <code>NULLFAIL</code>: valid ECDSA signatures must be strictly DER-encoded and have a low-S value; invalid ECDSA signature must be the empty push
## <code>MINIMALDATA</code>: all pushes must be minimally encoded
## <code>CLEANSTACK</code>: require that only a single stack element remains after evaluation
## <code>MINIMALIF</code>: the argument of <code>IF</code>/<code>NOTIF</code> must be exactly 0x01 or empty push
## If any of the above steps failed, the validator should stop and output the ''invalid'' state.
# Check the **upgradeable rules**
## The version of <code>to_sign</code> must be 0 or 2.
## The use of NOPs reserved for upgrades is forbidden.
## The use of segwit versions greater than 1 are forbidden.
## If any of the above steps failed, the validator should stop and output the ''inconclusive'' state.
# Let ''T'' by the nLockTime of <code>to_sign</code> and ''S'' be the nSequence of the first input of <code>to_sign</code>. Output the state ''valid at time T and age S''.


# let <code>p</code> be the pubkey-hash <code>pkh(P)</code> for the pubkey <code>P</code>, contained in <code>a</code>
=== Signing ===
# let <code>x</code> be the private key associated with <code>P</code> so that <code>pkh(xG) = p</code>
# let <code>digest</code> be <code>SHA56d("Bitcoin Signed Message:\n"||m)</code>
# create a compact signature <code>sig</code> (aka "recoverable ECDSA signature") using <code>x</code> on <code>digest</code>


The resulting proof is <code>sig</code>, serialized using the base64 encoding.
Signers who control an address ''A'' who wish to sign a message ''m'' act as follows:


=== Verifying ===
# They construct <code>to_spend</code> and <code>to_sign</code> as specified above, using the scriptPubKey of ''A'' for <code>message_challenge</code> and tagged hash of ''m'' as <code>message_hash</code>.
# Optionally, they may set nLockTime of <code>to_sign</code> or nSequence of its first input.
# Optionally, they may add any additional outputs to <code>to_sign</code> that they wish to prove control of.
# They satisfy <code>to_sign</code> as they would any other transaction.


Given the P2PKH address <code>a</code>, the message <code>m</code>, the compact signature <code>sig</code>, and the pubkey-hash function <code>pkh(P) = ripemd160(sha256(P))</code>:
They then encode their signature, choosing either ''simple'' or ''full'' as follows:


# let <code>p</code> be the pubkey-hash <code>pkh(P)</code> for the pubkey <code>P</code>, contained in <code>a</code>
* If they added no inputs to <code>to_sign</code>, left nSequence and nLockTime at 0, and ''A'' is a Segwit address (either pure or P2SH-wrapped), then they may base64-encode <code>message_signature</code>
# let <code>digest</code> be <code>SHA56d("Bitcoin Signed Message:\n"||m)</code>
* Otherwise they must base64-encode <code>to_sign</code>.
# attempt pubkey recovery for <code>digest</code> using the signature <code>sig</code> and store the resulting pubkey into <code>Q</code>
## fail verification if pubkey recovery above fails
# let <code>q</code> be the pubkey-hash <code>pkh(Q)</code> for the pubkey <code>Q</code>
# if <code>p == q</code>, the proof is valid, otherwise it is invalid


== Compatibility ==
== Compatibility ==
Line 141: Line 146:
== Reference implementation ==
== Reference implementation ==


# Pull request to Bitcoin Core: https://github.com/bitcoin/bitcoin/pull/16440
* Bitcoin Core pull request (basic support) at: https://github.com/bitcoin/bitcoin/pull/24058


== Acknowledgements ==
== Acknowledgements ==


Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, and many others for their feedback on the specification.
Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, Andrew Poelstra, and many others for their feedback on the specification.


== References ==
== References ==
Line 155: Line 160:
This document is licensed under the Creative Commons CC0 1.0 Universal license.
This document is licensed under the Creative Commons CC0 1.0 Universal license.


== Consensus and standard flags ==
== Test vectors ==
 
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 super-set 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.
=== Message hashing ===


=== Consensus rules ===
Message hashes are BIP340-tagged hashes of a message, i.e. sha256_tag(m), where tag = <code>BIP0322-signed-message</code>, and m is the message as is without length prefix or null terminator:


* P2SH: evaluate P2SH ([https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki BIP16]) subscripts
* Message = "" (empty string): <code>c90c269c4f8fcbe6880f72a721ddfbf1914268a794cbb21cfafee13770ae19f1</code>
* DERSIG: enforce strict DER ([https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki BIP66]) compliance
* Message = "Hello World": <code>f0eb03b1a75ac6d9847f55c624a99169b5dccba2a31f5b23bea77ba270de0a7a</code>
* NULLDUMMY: enforce NULLDUMMY ([https://github.com/bitcoin/bips/blob/master/bip-0147.mediawiki BIP147])
* CHECKLOCKTIMEVERIFY: enable CHECKLOCKTIMEVERIFY ([https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki BIP65])
* CHECKSEQUENCEVERIFY: enable CHECKSEQUENCEVERIFY ([https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki BIP112])
* WITNESS: enable WITNESS ([https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki BIP141])


=== Policy rules ===
=== Message signing ===
 
All of the above, plus (subject to change):
 
* STRICTENC: non-strict 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: v1-16 witness programs are non-standard (i.e. forbidden)
* WITNESS_PUBKEYTYPE: public keys in segregated witness scripts must be compressed
* CONST_SCRIPTCODE: OP_CODESEPARATOR and FindAndDelete fail any non-segwit scripts
 
== Test vectors ==


(TODO: update test vectors, which are based on previous iteration where signature proofs contained additional data)
Given below parameters:


== Native segwit test vector ==
* private key <code>L3VFeEujGtevx9w18HD1fhRbCH67Az2dpCymeRE1SoPK6XQtaN2k</code>
* corresponding address <code>bc1q9vza2e8x573nczrlzms0wvx3gsqjx7vavgkx0l</code>


<pre>
Produce signatures:
address      = bcrt1qe7nte4zk4ayly5tc53dtdjupgkz0lr8azx3rzz
scriptpubkey = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd
message      = hello
preimage    = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd426974636f696e205369
              676e6564204d6573736167653a0a68656c6c6f
              (scriptpubkey || "Bitcoin Signed Message:\nhello")
sighash      = 790eef86c204f0bff969ff822121317aa34eff0215dbd30ccf031e7b2f3f0cc1
              (sha256d(preimage), displayed in big-endian)
</pre>


The proof becomes:
* Message = "" (empty string): <code>AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> or <code>AkgwRQIhAPkJ1Q4oYS0htvyuSFHLxRQpFAY56b70UvE7Dxazen0ZAiAtZfFz1S6T6I23MWI2lK/pcNTWncuyL8UL+oMdydVgzAEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy</code>
* Message = "Hello World": <code>AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> or <code>AkgwRQIhAOzyynlqt93lOKJr+wmmxIens//zPzl9tqIOua93wO6MAiBi5n5EyAcPScOjf1lAqIUIQtr3zKNeavYabHyR8eGhowEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy</code>


<pre>
=== Transaction Hashes ===
HEX:    01000000010002473044022075b4fb40421d55c55462879cb352a85eeb3af2138d3f0290
        2c9143f12870f5f70220119c2995c1661138142f3899c1fd6d1af7e790e0e081be72db9c
        e7bf5b5b932901210290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e7c1dee9e
        a6e2dcd869


Base64: AQAAAAEAAkcwRAIgdbT7QEIdVcVUYoecs1KoXus68hONPwKQLJFD8Shw9fcCIBGcKZXBZhE4
to_spend:
        FC84mcH9bRr355Dg4IG+ctuc579bW5MpASECkL7M0Ctz7KV0Z7K28eRxYam3al5nWG58He6e
        puLc2Gk=
</pre>


Split into components:
* Message = "" (empty string): <code>c5680aa69bb8d860bf82d4e9cd3504b55dde018de765a91bb566283c545a99a7</code>
* Message = "Hello World": <code>b79d196740ad5217771c1098fc4a4b51e0535c32236c71f1ea4d61a2d603352b</code>


{|class="wikitable" style="text-align: center;"
to_sign:
|-
!Type
!Length
!Name
!Value
!Comment
|-
|Uint32||4||flags||<code>01000000</code>||proof format version
|-
|Uint8||1||entries||<code>01</code>||1 entry
|-
|VarInt||1-8||scriptsiglen||<code>00</code>||0 byte scriptsig
|-
|VarInt||1-8||wit entries||<code>02</code>||2 witness stack entries
|-
|VarInt||1-8||entry1len||<code>47</code>||71 byte entry
|-
|Uint8[71]||71||entry1||<code>3044022075b4fb40421d55c55462879cb352a85eeb3af213
8d3f02902c9143f12870f5f70220119c2995c1661138142f
3899c1fd6d1af7e790e0e081be72db9ce7bf5b5b932901</code>||Witness stack item 1
|-
|VarInt||1-8||entry2len||<code>21</code>||33 byte entry
|-
|Uint8[33]||33||entry2||<code>0290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e
7c1dee9ea6e2dcd869</code>||Witness stack item 2
|}


The above test vector is for a bech32 P2WPKH (native segwit) address. (Once BIP solidifies, will add test vector for other types.)
* Message = "" (empty string): <code>1e9654e951a5ba44c8604c4de6c67fd78a27e81dcadcfe1edf638ba3aaebaed6</code>
* Message = "Hello World": <code>88737ae86f2077145f93cc4b153ae9a1cb8d56afa511988c149c5c8c9d93bddf</code>

Latest revision as of 18:07, 31 May 2024

This page describes a BIP (Bitcoin Improvement Proposal).
Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

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: Karl-Johan Alm <karljohan-alm@garage.co.jp>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0322
  Status: Draft
  Type: Standards Track
  Created: 2018-09-10
  License: CC0-1.0

Abstract

A standard for interoperable signed messages based on the Bitcoin Script format, either for proving fund availability, or committing to a message as the intended recipient of funds sent to the invoice address.

Motivation

The current message signing standard only works for P2PKH (1...) invoice addresses. We propose to extend and generalize the standard by using a Bitcoin Script based approach. This ensures that any coins, no matter what script they are controlled by, can in-principle be signed for. For easy interoperability with existing signing hardware, we also define a signature message format which resembles a Bitcoin transaction (except that it contains an invalid input, so it cannot be spent on any real network).

Additionally, the current message signature format uses ECDSA signatures which do not commit to the public key, meaning that they do not actually prove knowledge of any secret keys. (Indeed, valid signatures can be tweaked by 3rd parties to become valid signatures on certain related keys.)

Ultimately no message signing protocol can actually prove control of funds, both because a signature is obsolete as soon as it is created, and because the possessor of a secret key may be willing to sign messages on others' behalf even if it would not sign actual transactions. No signmessage protocol can fix these limitations.

Types of Signatures

This BIP specifies three formats for signing messages: legacy, simple and full. Additionally, a variant of the full format can be used to demonstrate control over a set of UTXOs.

Legacy

New proofs should use the new format for all invoice address formats, including P2PKH.

The legacy format MAY be used, but must be restricted to the legacy P2PKH invoice address format.

Simple

A simple signature consists of a witness stack, consensus encoded as a vector of vectors of bytes, and base64-encoded. Validators should construct to_spend and to_sign as defined below, with default values for all fields except that

  • message_hash is a BIP340-tagged hash of the message, as specified below
  • message_challenge in to_spend is set to the scriptPubKey being signed with
  • message_signature in to_sign is set to the provided simple signature.

and then proceed as they would for a full signature.

Full

Full signatures follow an analogous specification to the BIP-325 challenges and solutions used by Signet.

Let there be two virtual transactions to_spend and to_sign.

The to_spend transaction is: 

   nVersion = 0
   nLockTime = 0
   vin[0].prevout.hash = 0000...000
   vin[0].prevout.n = 0xFFFFFFFF
   vin[0].nSequence = 0
   vin[0].scriptSig = OP_0 PUSH32[ message_hash ]
   vin[0].scriptWitness = []
   vout[0].nValue = 0
   vout[0].scriptPubKey = message_challenge

where message_hash is a BIP340-tagged hash of the message, i.e. sha256_tag(m), where tag = BIP0322-signed-message and m is the message as is without length prefix or null terminator, and message_challenge is the to be proven (public) key script.

The to_sign transaction is: 

   nVersion = 0 or (FULL format only) as appropriate (e.g. 2, for time locks)
   nLockTime = 0 or (FULL format only) as appropriate (for time locks)
   vin[0].prevout.hash = to_spend.txid
   vin[0].prevout.n = 0
   vin[0].nSequence = 0 or (FULL format only) as appropriate (for time locks)
   vin[0].scriptWitness = message_signature
   vout[0].nValue = 0
   vout[0].scriptPubKey = OP_RETURN

A full signature consists of the base64-encoding of the to_sign transaction in standard network serialisation once it has been signed.

Full (Proof of Funds)

A signer may construct a proof of funds, demonstrating control of a set of UTXOs, by constructing a full signature as above, with the following modifications.

  • All outputs that the signer wishes to demonstrate control of are included as additional inputs of to_sign, and their witness and scriptSig data should be set as though these outputs were actually being spent.

Unlike an ordinary signature, validators of a proof of funds need access to the current UTXO set, to learn that the claimed inputs exist on the blockchain, and to learn their scriptPubKeys.

Detailed Specification

For all signature types, except legacy, the to_spend and to_sign transactions must be valid transactions which pass all consensus checks, except of course that the output with prevout 000...000:FFFFFFFF does not exist.

Verification

A validator is given as input an address A (which may be omitted in a proof-of-funds), signature s and message m, and outputs one of three states

  • valid at time T and age S indicates that the signature has set timelocks but is otherwise valid
  • inconclusive means the validator was unable to check the scripts
  • invalid means that some check failed

Verification Process

Validation consists of the following steps:

  1. Basic validation
    1. Compute the transaction to_spend from m and A
    2. Decode s as the transaction to_sign
    3. If s was a full transaction, confirm all fields are set as specified above; in particular that
      • to_sign has at least one input and its first input spends the output of to_spend
      • to_sign has exactly one output, as specified above
    4. Confirm that the two transactions together satisfy all consensus rules, except for to_spend's missing input, and except that nSequence of to_sign's first input and nLockTime of to_sign are not checked.
  2. (Optional) If the validator does not have a full script interpreter, it should check that it understands all scripts being satisfied. If not, it should stop here and output inconclusive.
  3. Check the **required rules**:
    1. All signatures must use the SIGHASH_ALL flag.
    2. The use of CODESEPARATOR or FindAndDelete is forbidden.
    3. LOW_S, STRICTENC and NULLFAIL: valid ECDSA signatures must be strictly DER-encoded and have a low-S value; invalid ECDSA signature must be the empty push
    4. MINIMALDATA: all pushes must be minimally encoded
    5. CLEANSTACK: require that only a single stack element remains after evaluation
    6. MINIMALIF: the argument of IF/NOTIF must be exactly 0x01 or empty push
    7. If any of the above steps failed, the validator should stop and output the invalid state.
  4. Check the **upgradeable rules**
    1. The version of to_sign must be 0 or 2.
    2. The use of NOPs reserved for upgrades is forbidden.
    3. The use of segwit versions greater than 1 are forbidden.
    4. If any of the above steps failed, the validator should stop and output the inconclusive state.
  5. Let T by the nLockTime of to_sign and S be the nSequence of the first input of to_sign. Output the state valid at time T and age S.

Signing

Signers who control an address A who wish to sign a message m act as follows:

  1. They construct to_spend and to_sign as specified above, using the scriptPubKey of A for message_challenge and tagged hash of m as message_hash.
  2. Optionally, they may set nLockTime of to_sign or nSequence of its first input.
  3. Optionally, they may add any additional outputs to to_sign that they wish to prove control of.
  4. They satisfy to_sign as they would any other transaction.

They then encode their signature, choosing either simple or full as follows:

  • If they added no inputs to to_sign, left nSequence and nLockTime at 0, and A is a Segwit address (either pure or P2SH-wrapped), then they may base64-encode message_signature
  • Otherwise they must base64-encode to_sign.

Compatibility

This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.

Reference implementation

Acknowledgements

Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, Andrew Poelstra, and many others for their feedback on the specification.

References

  1. Original mailing list thread: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-March/015818.html

Copyright

This document is licensed under the Creative Commons CC0 1.0 Universal license.

Test vectors

Message hashing

Message hashes are BIP340-tagged hashes of a message, i.e. sha256_tag(m), where tag = BIP0322-signed-message, and m is the message as is without length prefix or null terminator:

  • Message = "" (empty string): c90c269c4f8fcbe6880f72a721ddfbf1914268a794cbb21cfafee13770ae19f1
  • Message = "Hello World": f0eb03b1a75ac6d9847f55c624a99169b5dccba2a31f5b23bea77ba270de0a7a

Message signing

Given below parameters:

  • private key L3VFeEujGtevx9w18HD1fhRbCH67Az2dpCymeRE1SoPK6XQtaN2k
  • corresponding address bc1q9vza2e8x573nczrlzms0wvx3gsqjx7vavgkx0l

Produce signatures:

  • Message = "" (empty string): AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI= or AkgwRQIhAPkJ1Q4oYS0htvyuSFHLxRQpFAY56b70UvE7Dxazen0ZAiAtZfFz1S6T6I23MWI2lK/pcNTWncuyL8UL+oMdydVgzAEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy
  • Message = "Hello World": AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI= or AkgwRQIhAOzyynlqt93lOKJr+wmmxIens//zPzl9tqIOua93wO6MAiBi5n5EyAcPScOjf1lAqIUIQtr3zKNeavYabHyR8eGhowEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy

Transaction Hashes

to_spend:

  • Message = "" (empty string): c5680aa69bb8d860bf82d4e9cd3504b55dde018de765a91bb566283c545a99a7
  • Message = "Hello World": b79d196740ad5217771c1098fc4a4b51e0535c32236c71f1ea4d61a2d603352b

to_sign:

  • Message = "" (empty string): 1e9654e951a5ba44c8604c4de6c67fd78a27e81dcadcfe1edf638ba3aaebaed6
  • Message = "Hello World": 88737ae86f2077145f93cc4b153ae9a1cb8d56afa511988c149c5c8c9d93bddf
Retrieved from "https://en.bitcoin.it/w/index.php?title=BIP_0322&oldid=70255"