---
robots: noindex, nofollow
---

musign
======

Musign is a simple tool to create multi-party signatures for files, and to
verify those signatures, using the Schnorr signature algorithm over the
secp256k1 elliptic curve.

Creating a simple (single-signer) key pair
------------------------------------------

A new private key can be generated with the `genkey` command:

$ musign genkey
Please enter the path in which to save the key (~/.musign/default): <ENTER>
Please enter a password to protect the secret key.

Password: <PASS>
Password (one more time): <PASS>
Deriving a key from the password in order to encrypt the secret key... done

The secret key was saved as ~/.musign/default -- Keep it secret!
The public key was saved as ~/.musign/default.pub -- This can be public.

Files signed using this key pair can be verified with the following command:
musign verify --pubkey mu1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
$

The private key is encrypted with ChaCha20 as the stream cipher, Poly1305 as the
MAC, and Argon2id as the key derivation function, and stored in the file path
specified.

The public key is bech32-encoded and stored in the same file path but with the
".pub" extension. It is also displayed on the final line of the terminal
output.

Creating an aggregate verification pubkey
-----------------------------------------

Musign can use the properties of Schnorr signatures to create combine multiple
distinct public keys into single verification key which requires the cooperation
of all of the corresponding private key holders to generate a valid signature.

$ musign combine -p KEY1 -p KEY2 [-p KEY3...]
Multiple public keys provided; calculating aggregate verification key.
Files signed using this aggregate key can be verified with the following command:
musign verify --pubkey mu1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
$

Signing a file with a single key
--------------------------------

Creating a signature requires specifying which file(s) to sign, which key to
use, and where to store the resulting signature:

$ musign sign FILES... [-o sigpath.sig] ([-i keypath] | [-s secret])
Password: <PASS>
Deriving a key from the password and decrypting the secret key... done
Signature generated and saved to sigpath.sig
$

If no key is specified, `~/.musign/default` is used.

If a single file is specified, the output defaults to signed file's path with
the ".sig" extension added. If multiple files are signed, specifying the output
path is required.

Musign uses SHA-512 to reduce the file(s) to be signed to a compact message
value, which is then signed with the secret key over the secp256k1 curve.

Creating a multi-key aggregate signature
----------------------------------------

Musign is capable of using the MuSig signature aggregation mechanism[MuSig] to
interactively construct a compact, efficient aggregate signature.

Using multiple keys to generate a single, compact signature is necessarily a
multi-step process for security reasons. First each signer commits to hash of
the public portion of a value they will use in their signature. Only once they
have seen a commitment from all the other signers is it safe to reveal their own
preimage value, with knowledge of all preimages being required to sign.

$ musign setup FILES [-f statepath] -p PUBKEY1 -p PUBKEY2...
Initialized signing plan and saved to ./default.musign
Files signed using this aggregate key can be verified with the following command:
musign verify --pubkey mu1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
$

All signing state is contained within the `statepath` file, which defaults to
`default.musign`. This file is provided to the `sign` command for each step of
the signing process, during which it is updated with whatever values the signer
can provide.

$ musign sign -f default.musign ([-i keypath] | [-s secret])
(Output TBD)

With each invocation musign accomplishes whatever steps of the multi-party
signing process that it can, then performs an in-place update of the statefile.
The current state and required next steps of the signing operation are reported
to the user on the command line. The current signing state can be queried from
the statefile at any time as well:

$ musign info -f default.musign
(Output TBD)

The statefile can either be passed around among the signers in a serial fashion,
or it can be copied to each of the signers and signed in parallel. In the
latter case, the results need to be merged before progress can continue:

$ musign combine FILES... -o default.musign
(Output TBD)

Once all signing steps have been accomplished, the signature file is output by
the last invocation of `musig sign`.

Verifying a file signature
--------------------------

As the signatures for single-owner keys and multi-key aggregates are
indistinguishable, a single command verifies both:

$ musign verify filename [-x sigpath] ([-i keypath] | [-p pubkey])
filename: OK
$

[MuSig]: https://eprint.iacr.org/2018/068