diff options
Diffstat (limited to 'bip-0322.mediawiki')
| -rw-r--r-- | bip-0322.mediawiki | 255 |
1 files changed, 139 insertions, 116 deletions
diff --git a/bip-0322.mediawiki b/bip-0322.mediawiki index 5191143..55a751f 100644 --- a/bip-0322.mediawiki +++ b/bip-0322.mediawiki @@ -13,157 +13,180 @@ == 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. == 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 <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container. - -Two actions "Sign" and "Verify" are defined along with two *purposes* "SignMessage" and "ProveFunds". - -=== SignatureProof container === - -{|class="wikitable" style="text-align: center;" -|- -!Type -!Length -!Name -!Comment -|- -|Uint32||4||flags||standard flags (1-to-1 with standard flags in Bitcoin Core) -|- -|VarInt||1-8||msglen||Number of bytes in message string, excluding NUL termination -|- -|Char*||[msglen]||msg||The message being signed for all subjects, excluding NUL termination -|- -|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> -|} +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). -The above is followed by [entries] number of signature entries: +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.) -{|class="wikitable" style="text-align: center;" -|- -!Type -!Length -!Name -!Comment -|- -|VarInt||1-8||scriptsiglen||Number of bytes in scriptSig data -|- -|Uint8*||[scriptsiglen]||scriptsig||ScriptSig data -|- -|VarInt||1-8||witlen||Number of bytes in witness data -|- -|Uint8*||[witlen]||wit||Witness -|} +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. -In some cases, the scriptsig or wit may be empty. If both are empty, the proof is incomplete. +== Types of Signatures == -=== Result Codes === +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. -A verification call will return a result code according to the table below. +=== Legacy === -{|class="wikitable" style="text-align: center;" -|- -!Code -!Description -|- -|INCOMPLETE||One or several of the given challenges had an empty proof. The prover may need some other entity to complete the proof. -|- -|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. -|- -|VALID||All proofs were deemed valid. -|- -|INVALID||One or more of the given proofs were invalid -|- -|SPENT||One or more of the claimed UTXO:s has been spent -|- -|ERROR||An error was encountered -|} +New proofs should use the new format for all invoice address formats, including P2PKH. -== Signing and Verifying == +The legacy format MAY be used, but must be restricted to the legacy P2PKH invoice address format. -Let there be an empty set `inputs` which is populated and tested at each call to one of the actions below. +=== Simple === -=== Purpose: SignMessage === +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 -The "SignMessage" purpose generates a sighash based on a scriptPubKey and a message. It emits a VALID verification result code unless otherwise stated. +* <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 +* <code>message_signature</code> in <code>to_sign</code> is set to the provided simple signature. -# 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> -# Define the message pre-image as the sequence "Bitcoin Message:" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD) -# Let sighash = sha256(sha256(scriptPubKey || pre-image)) +and then proceed as they would for a full signature. -=== Purpose: ProveFunds === +=== Full === -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. +Full signatures follow an analogous specification to the BIP-325 challenges and solutions used by Signet. -# Let txid be the transaction ID of the transaction, and vout be the output index corresponding to the index of the output being spent -# Return INVALID if the txid:vout pair already exists in `inputs` set, otherwise insert it -# 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> -# Extract scriptPubKey from transaction output -# 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> -#* the string "POF:" -#* 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) -#* all transactions being proven for, as binary txid (little endian uint256) followed by index (little endian uint32), each separated by a single `0x00` byte -# Let sighash = sha256(sha256(scriptPubKey || pre-image)) +Let there be two virtual transactions <code>to_spend</code> and <code>to_sign</code>. -=== Action: Sign === +The <code>to_spend</code> transaction is: -The "Sign" action takes as input a purpose. It returns a signature or fails. + 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 -# Obtain the sighash and scriptPubKey from the purpose; 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 - -=== Action: Verify === - -The "Verify" action takes as input a standard flags value, a script sig, an optional witness, and a purpose. -It emits one of INCONCLUSIVE, VALID, INVALID, or ERROR. - -# Obtain the sighash and scriptPubKey from the purpose; pass on result code if not VALID -# If one or more of the standard flags are unknown, return INCONCLUSIVE -# Verify Script with flags=standard flags, scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash -# Return VALID if verify succeeds, otherwise return INVALID - -=== Multiple Proofs === - -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. - -Note that the order of the entries in the proof must match the order of the entries given by the verifier. - -* If any of the proofs are empty during a verification process, skip the verification and set the INCOMPLETE flag -* If a verification call returns ERROR or INVALID, return ERROR or INVALID immediately, ignoring as yet unverified entries -* After all verifications complete, -** return INCONCLUSIVE if any verification call returned INCONCLUSIVE -** return SPENT if any verification call returned SPENT -** return INCOMPLETE if the INCOMPLETE flag is set -** return VALID +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. -== Compatibility == +The <code>to_sign</code> 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 <code>to_sign</code> 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. + +* <code>message_challenge</code> is unused and shall be set to <code>OP_TRUE</code> +* Similarly, <code>message_signature</code> is then empty. +* 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. + +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 <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. -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. +=== Verification === -== Rationale == +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 -<references/> +==== Verification Process ==== + +Validation consists of the following steps: + +# 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''. + +=== Signing === + +Signers who control an address ''A'' who wish to sign a message ''m'' act as follows: + +# 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. + +They then encode their signature, choosing either ''simple'' or ''full'' as follows: + +* 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> +* Otherwise they must base64-encode <code>to_sign</code>. + +== Compatibility == + +This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above. == Reference implementation == -To do. +* Bitcoin Core pull request (basic support) at: https://github.com/bitcoin/bitcoin/pull/24058 == Acknowledgements == -TODO +Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, Andrew Poelstra, and many others for their feedback on the specification. == References == # Original mailing list thread: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-March/015818.html -# Pull request, with comments: https://github.com/bitcoin/bips/pull/725 == 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 = <code>BIP0322-signed-message</code>, and m is the message as is without length prefix or null terminator: + +* Message = "" (empty string): <code>c90c269c4f8fcbe6880f72a721ddfbf1914268a794cbb21cfafee13770ae19f1</code> +* Message = "Hello World": <code>f0eb03b1a75ac6d9847f55c624a99169b5dccba2a31f5b23bea77ba270de0a7a</code> + +=== Message signing === + +Given below parameters: + +* private key <code>L3VFeEujGtevx9w18HD1fhRbCH67Az2dpCymeRE1SoPK6XQtaN2k</code> +* corresponding address <code>bc1q9vza2e8x573nczrlzms0wvx3gsqjx7vavgkx0l</code> + +Produce signatures: + +* Message = "" (empty string): <code>AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> +* Message = "Hello World": <code>AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> + +=== Transaction Hashes === + +to_spend: + +* Message = "" (empty string): <code>c5680aa69bb8d860bf82d4e9cd3504b55dde018de765a91bb566283c545a99a7</code> +* Message = "Hello World": <code>b79d196740ad5217771c1098fc4a4b51e0535c32236c71f1ea4d61a2d603352b</code> + +to_sign: + +* Message = "" (empty string): <code>1e9654e951a5ba44c8604c4de6c67fd78a27e81dcadcfe1edf638ba3aaebaed6</code> +* Message = "Hello World": <code>88737ae86f2077145f93cc4b153ae9a1cb8d56afa511988c149c5c8c9d93bddf</code> |