BIP: 322
  Layer: Applications
  Title: Generic Signed Message Format
  Authors: Karl-Johan Alm 
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0322
  Status: Draft
  Type: Specification
  Assigned: 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). The Proof of Funds variant allows demonstrating control of a set of UTXOs. The list of UTXOs may or may not be related to the address being signed with (the message_challenge). But in any case, the UTXO list does not aim to prove completeness (e.g. it does NOT mean: "these are all UTXOs that exist for an address") nor that they are unspent (e.g. a validator must consult the blockchain to verify that). 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 message signing protocol can fix these limitations. Finally, this BIP only addresses the use case where a signer shows they will be able to control funds sent to the invoice address. Proving that a signer sent a prior transaction is not possible using this BIP. == 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. {| class="wikitable" |- style="font-weight:bold;" ! ! Compatible script types ! Signature format |- | Legacy | P2PKH, P2SH-P2WPKH1, P2WPKH1 | compact, public key recoverable ECDSA signature, base64-encoded |- | Simple | P2WPKH, P2WSH2, P2TR2
| witness stack, consensus encoded and base64-encoded |- | Full | all | full to_sign transaction, consensus and base64-encoded |- | Full (PoF) | all | full to_sign transaction, consensus and base64-encoded |} 1: Possible on a technical level but should NOT be used anymore in the context of this BIP.
2: Excluding time lock scripts. === 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 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].scriptSig = [] or (FULL format only) as appropriate (for non segwit-native transactions) 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. 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 remain unspent. An offline validator therefore can only attest to the cryptographic validity of the additional inputs' witness stack, but not its blockchain state. An attested list of UTXOs can also never prove that there don't exist more UTXOs for a certain address. == 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 ==== Verification Process ==== Validation consists of the following steps: # Basic validation ## Compute the transaction to_spend from ''m'' and ''A'' ## Decode ''s'' as the transaction to_sign ## 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 ## 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. # (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 CODESEPARATOR or FindAndDelete is forbidden. ## 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 ## MINIMALDATA: all pushes must be minimally encoded ## CLEANSTACK: require that only a single stack element remains after evaluation ## MINIMALIF: the argument of IF/NOTIF 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 to_sign 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 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 nVersion/nLockTime of to_sign or nSequence of its first input.
  3. Optionally, they may add any additional inputs 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: == 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, Luke Dashjr, 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 == Basic test vectors for message hashing, transaction hashes and "simple" variant test cases can be found in [[bip-0322/basic-test-vectors.json|basic-test-vectors.json]]. Generated test vectors for more "simple" and "full" variant test cases can be found in [[bip-0322/generated-test-vectors.json|generated-test-vectors.json]]. They were generated using [https://github.com/guggero/btcd/blob/f0d87198/btcutil/bip322/bip322_test.go#L910 this code].