Expand description
§Subkey
Subkey is a commandline utility included with Substrate. It allows generating and restoring keys
for Substrate based chains such as Polkadot, Kusama and a growing number of parachains and
Substrate based projects.
subkey
provides a few sub-commands to generate keys, check keys, sign messages, verify
messages, etc…
You can see the full list of commands with subkey --help
. Most commands have additional help
available with for instance subkey generate --help
for the generate
command.
§Safety first
subkey
does not need an internet connection to work. Indeed, for the best security, you should
be using subkey
on a machine that is not connected to the internet.
subkey
deals with seeds and private keys. Make sure to use subkey
in a safe
environment (ie. no one looking over your shoulder) and on a safe computer (ie. no one able to
check your command history).
If you save any output of subkey
into a file, make sure to apply proper permissions and/or
delete the file as soon as possible.
§Usage
The following guide explains some of the subkey
commands. For the full list and the most up
to date documentation, make sure to check the integrated help with subkey --help
.
§Install with Cargo
You will need to have the Substrate build dependencies to install Subkey. Use the following two commands to install the dependencies and Subkey, respectively:
Command:
# Install only `subkey`, at a specific version of the subkey crate
cargo install --force subkey --git https://github.com/paritytech/substrate --version <SET VERSION> --locked
# If you run into issues building, you likely are missing deps defined in https://docs.substrate.io/install/
§Run in a container
# Use `--pull=always` with the `latest` tag, or specify a version in a tag
docker run -it --pull=always docker.io/parity/subkey:latest <command to subkey>
§Generate a random account
Generating a new key is as simple as running:
subkey generate
The output looks similar to:
Secret phrase `hotel forest jar hover kite book view eight stuff angle legend defense` is account:
Secret seed: 0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
Public key (hex): 0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515
Account ID: 0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515
SS58 Address: 5Hpm9fq3W3dQgwWpAwDS2ZHKAdnk86QRCu7iX4GnmDxycrte
☠️ DO NT RE-USE ANY OF THE SEEDS AND SECRETS FROM THIS PAGE ☠️.
You can read more about security and risks in SECURITY.md and in the Polkadot Wiki.
The output above shows a secret phrase (also called mnemonic phrase) and the secret seed (also called Private Key). Those 2 secrets are the pieces of information you MUST keep safe and secret. All the other information below can be derived from those secrets.
The output above also show the public key and the Account ID. Those are the independent from the network where you will use the key.
The SS58 address (or Public Address) of a new account is a representation of the public keys of an account for a given network (for instance Kusama or Polkadot).
You can read more about the SS58 format in the Substrate Docs and see the list of reserved prefixes in the SS58 Registry.
For instance, considering the previous seed
0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
the SS58 addresses are:
- Polkadot:
16m4J167Mptt8UXL8aGSAi7U2FnPpPxZHPrCgMG9KJzVoFqM
- Kusama:
JLNozAv8QeLSbLFwe2UvWeKKE4yvmDbfGxTuiYkF2BUMx4M
§Json output
subkey
can also generate the output as json. This is useful for automation.
command:
subkey generate --output-type json
output:
{
"accountId": "0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515",
"publicKey": "0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515",
"secretPhrase": "hotel forest jar hover kite book view eight stuff angle legend defense",
"secretSeed": "0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d",
"ss58Address": "5Hpm9fq3W3dQgwWpAwDS2ZHKAdnk86QRCu7iX4GnmDxycrte"
}
So if you only want to get the secretSeed
for instance, you can use:
command:
subkey generate --output-type json | jq -r .secretSeed
output:
0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
§Additional user-defined password
subkey
supports an additional user-defined secret that will be appended to the seed. Let’s see
the following example:
subkey generate --password extra_secret
output:
Secret phrase `soup lyrics media market way crouch elevator put moon useful question wide` is account:
Secret seed: 0xe7cfd179d6537a676cb94bac3b5c5c9cb1550e846ac4541040d077dfbac2e7fd
Public key (hex): 0xf6a233c3e1de1a2ae0486100b460b3ce3d7231ddfe9dadabbd35ab968c70905d
Account ID: 0xf6a233c3e1de1a2ae0486100b460b3ce3d7231ddfe9dadabbd35ab968c70905d
SS58 Address: 5He5pZpc7AJ8evPuab37vJF6KkFDqq9uDq2WXh877Qw6iaVC
Using the inspect
command (see more details below), we see that knowing only the secret
seed is no longer sufficient to recover the account:
subkey inspect "soup lyrics media market way crouch elevator put moon useful question wide"
which recovers the account 5Fe4sqj2K4fRuzEGvToi4KATqZfiDU7TqynjXG6PZE2dxwyh
and not
5He5pZpc7AJ8evPuab37vJF6KkFDqq9uDq2WXh877Qw6iaVC
as we expected. The additional user-defined
password (extra_secret
in our example) is now required to fully recover the account. Let’s
inspect the the previous mnemonic, this time passing also the required password
as shown
below:
subkey inspect --password extra_secret "soup lyrics media market way crouch elevator put moon useful question wide"
This time, we properly recovered 5He5pZpc7AJ8evPuab37vJF6KkFDqq9uDq2WXh877Qw6iaVC
.
§Inspecting a key
If you have some data about a key, subkey inspect
will help you discover more information
about it.
If you have secrets that you would like to verify for instance, you can use:
subkey inspect < mnemonic | seed >
If you have only public data, you can see a subset of the information:
subkey inspect --public < pubkey | address >
NOTE: While you will be able to recover the secret seed from the mnemonic, the opposite is not possible.
NOTE: For obvious reasons, the secrets cannot be recovered from passing public data
such as pubkey
or address
as input.
command:
subkey inspect 0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
output:
Secret Key URI `0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d` is account:
Secret seed: 0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
Public key (hex): 0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515
Account ID: 0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515
SS58 Address: 5Hpm9fq3W3dQgwWpAwDS2ZHKAdnk86QRCu7iX4GnmDxycrte
§Signing
subkey
allows using a secret key to sign a random message. The signature can then be
verified by anyone using your public key:
echo -n <msg> | subkey sign --suri <seed|mnemonic>
example:
MESSAGE=hello
SURI=0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d
echo -n $MESSAGE | subkey sign --suri $SURI
output:
9201af3788ad4f986b800853c79da47155f2e08fde2070d866be4c27ab060466fea0623dc2b51f4392f4c61f25381a62848dd66c5d8217fae3858e469ebd668c
NOTE: Each run of the sign
command will yield a different output. While each signature is
different, they are all valid.
§Verifying a signature
Given a message, a signature and an address, subkey
can verify whether the message has
been digitally signed by the holder (or one of the holders) of the private key for the given
address:
echo -n <msg> | subkey verify <sig> <address>
example:
MESSAGE=hello
URI=0xfec70cfbf1977c6965b5af10a4534a6a35d548eb14580594d0bc543286892515
SIGNATURE=9201af3788ad4f986b800853c79da47155f2e08fde2070d866be4c27ab060466fea0623dc2b51f4392f4c61f25381a62848dd66c5d8217fae3858e469ebd668c
echo -n $MESSAGE | subkey verify $SIGNATURE $URI
output:
Signature verifies correctly.
A failure looks like:
Error: SignatureInvalid
§Using the vanity generator
You can use the included vanity generator to find a seed that provides an address which includes the desired pattern. Be warned, depending on your hardware this may take a while.
command:
subkey vanity --network polkadot --pattern bob
output:
Generating key containing pattern 'bob'
best: 190 == top: 189
Secret Key URI `0x8c9a73097f235b84021a446bc2826a00c690ea0be3e0d81a84931cb4146d6691` is account:
Secret seed: 0x8c9a73097f235b84021a446bc2826a00c690ea0be3e0d81a84931cb4146d6691
Public key (hex): 0x1a8b32e95c1f571118ea0b84801264c3c70f823e320d099e5de31b9b1f18f843
Account ID: 0x1a8b32e95c1f571118ea0b84801264c3c70f823e320d099e5de31b9b1f18f843
SS58 Address: 1bobYxBPjZWRPbVo35aSwci1u5Zmq8P6J2jpa4kkudBZMqE
Bob
now got a nice address starting with their name:
1bobYxBPjZWRPbVo35aSwci1u5Zmq8P6J2jpa4kkudBZMqE.
Note: While Bob
, having a short name (3 chars), got a result rather quickly, it will take
much longer for Alice
who has a much longer name, thus the chances to generate a random
address that contains the chain alice
will be much smaller.
Enums§
Functions§
- Run the subkey command, given the appropriate runtime.