From 852bab073407b65b5e3e461baaa0541c4e0bc3d6 Mon Sep 17 00:00:00 2001 From: Chevdor Date: Tue, 31 Aug 2021 15:24:37 +0200 Subject: [PATCH] doc: subkey documentation (#9639) * doc: convert the adoc to md * add ref to UncheckedExtrinsic * Add references to the SS58 format * Add details about the inspect command * removing command that is no longer available * reorder display so ss58 representations show up next to each other * remove deprecated section * Add doc about the password option * fix fmt * minor fixes fix #6613 Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Co-authored-by: Squirrel Co-authored-by: David --- bin/utils/subkey/README.adoc | 91 ---------- bin/utils/subkey/README.md | 209 ++++++++++++++++++++++- bin/utils/subkey/SECURITY.md | 25 +++ client/cli/src/commands/utils.rs | 22 +-- client/cli/src/params/keystore_params.rs | 3 +- 5 files changed, 246 insertions(+), 104 deletions(-) delete mode 100644 bin/utils/subkey/README.adoc create mode 100644 bin/utils/subkey/SECURITY.md diff --git a/bin/utils/subkey/README.adoc b/bin/utils/subkey/README.adoc deleted file mode 100644 index 7c2a9cca0eb1e..0000000000000 --- a/bin/utils/subkey/README.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= Subkey - -Subkey is a commandline utility included with Substrate that generates or restores Substrate keys. - -`subkey` will use the http://wiki.polkadot.network/en/latest/polkadot/learn/cryptography/#keypairs-and-signing[sr25519] cryptography by default. If you need to use the older ed25519 cryptography to generate or restore your key pass the `--ed25519` flag to any of the commands. - -== Usage - -=== Generate a random account - -```bash -subkey generate -``` - -Will output a secret phrase("mnemonic phrase") and give you the secret seed("Private Key"), public key("Account ID") and SS58 address("Public Address") of a new account. DO NOT SHARE your mnemonic phrase or secret seed with ANYONE it will give them access to your funds. If someone is making a transfer to you they will only need your **Public Address**. - -=== Inspecting a key - -You can inspect a given URI (mnemonic, seed, public key, or address) and recover the public key and the address. - -```bash -subkey inspect -``` -_Example Output_: -``` -Secret Key URI `` is account: - Secret seed: 0xfac7959dbfe72f052e5a0c3c8d6530f202b02fd8f9f5ca3580ec8deb7797479e - Public key (hex): 0x46ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a - Public key (SS58): 5DfhGyQdFobKM8NsWvEeAKk5EQQgYe9AydgJ7rMB6E1EqRzV - Account ID: 0x46ebddef8cd9bb167dc30878d7113b7e168e6f0646beffd77d69d39bad76b47a - SS58 Address: 5DfhGyQdFobKM8NsWvEeAKk5EQQgYe9AydgJ7rMB6E1EqRzV -``` - -=== Signing - -`subkey` expects a message to come in on STDIN, one way to sign a message would look like this: - -```bash -echo -n | subkey sign --suri -``` -_Example Output_: -``` -a69da4a6ccbf81dbbbfad235fa12cf8528c18012b991ae89214de8d20d29c1280576ced6eb38b7406d1b7e03231df6dd4a5257546ddad13259356e1c3adfb509 -``` - -=== Verifying a signature - -```bash -echo -n | subkey verify
- -OUTPUT: -Signature verifies correctly. -``` - -=== 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. - -```bash -subkey vanity 1337 -``` - -=== Signing a transaction - -Sign a transaction from an encoded `Call`. - -```bash -subkey sign-transaction \ - --call \ - --nonce 0 \ - --suri \ - --password \ - --prior-block-hash -``` - -Will output a signed and encoded `UncheckedMortalCompactExtrinsic` as hex. - -=== Inspecting a module ID - -```bash -subkey module-id "py/trsry" --network kusama -``` -_Example Output_: -``` -Public Key URI `F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29` is account: - Network ID/version: kusama - Public key (hex): 0x6d6f646c70792f74727372790000000000000000000000000000000000000000 - Public key (SS58): F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29 - Account ID: 0x6d6f646c70792f74727372790000000000000000000000000000000000000000 - SS58 Address: F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29 -``` diff --git a/bin/utils/subkey/README.md b/bin/utils/subkey/README.md index 3e9ac0bddbdc1..fbb486247a770 100644 --- a/bin/utils/subkey/README.md +++ b/bin/utils/subkey/README.md @@ -1 +1,208 @@ -License: GPL-3.0-or-later WITH Classpath-exception-2.0 \ No newline at end of file +# 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. + +## Satefy 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 you commands 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`. + +### 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](./SECURITY.md) and in the [Polkadot Wiki](https://wiki.polkadot.network/docs/learn-account-generation). + +--- + +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 independant from the network where you will use the key. + +The **SS58 address** (or **Public Address**) of a new account is a reprensentation 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 wiki](https://github.com/paritytech/substrate/wiki/External-Address-Format-(SS58)) and see the list of reserved prefixes in the [Polkadot wiki](https://wiki.polkadot.network/docs/build-ss58-registry). + +For instance, considering the previous seed `0xa05c75731970cc7868a2fb7cb577353cd5b31f62dccced92c441acd8fee0c92d` the SS58 addresses are: +- Polkadot: `16m4J167Mptt8UXL8aGSAi7U2FnPpPxZHPrCgMG9KJzVoFqM` +- Kusama: `JLNozAv8QeLSbLFwe2UvWeKKE4yvmDbfGxTuiYkF2BUMx4M` + +### Json output + +`subkey` can calso 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 knowning 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 inpsect` 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 | subkey sign --suri + +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 | subkey verify
+ +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 his name: 1**bob**YxBPjZWRPbVo35aSwci1u5Zmq8P6J2jpa4kkudBZMqE. + +**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. + +## License + +License: GPL-3.0-or-later WITH Classpath-exception-2.0 diff --git a/bin/utils/subkey/SECURITY.md b/bin/utils/subkey/SECURITY.md new file mode 100644 index 0000000000000..672d2965c7eae --- /dev/null +++ b/bin/utils/subkey/SECURITY.md @@ -0,0 +1,25 @@ +# Keys and Security + +The following information is not exhaustive but meant to prevent the most common mistakes. +You can read more about security and risks in the [Polkadot Wiki](https://wiki.polkadot.network/docs/learn-account-generation). +The Polkadot network has a few **test networks**, e.g. **Westend**. Test networks are a great way to experiment and learn safely as you can lose tokens on those networks without any financial consequences. + +`subkey` generates and provides 2 pieces of **secret** information: +- **secret phrase**: a bunch of words, exactly 12 by default (can be 12, 15, 18, 21 or 24) +- **secret seed**: a big hexadecimal value + +There are 2 risks related to private keys: +- loss of keys: this can happen if you don't have a proper backup +- leak of the keys: this can unfortunately happen in many ways, including malware, phishing, key logger, backups on system that are online and not properly secured + +You want to ensure that: +- you **do not lose** those secrets +- **no one but you can access** those secrets + +☠️ **DO NOT SHARE** your mnemonic phrase or secret seed with ANYONE under **ANY** circumstances. Doing so would give them access to your funds and to send transactions on your behalf. + +☠️ If someone is asking for your **secret** phrase or **secret** seed, you can be **SURE** they are attempting to steal your funds. + +✅ It is however fine to share your **SS58 Address** as this is meant to be public information and is needed by anyone you want to be able to make transfer to or otherwise interact with your account. They will only ever need your **Public Address**. + +⚠️ While using the same key on multiple networks is possible, it is usually **not** recommended unless you have good motivations for doing so and understand the associated risks and drawbacks. diff --git a/client/cli/src/commands/utils.rs b/client/cli/src/commands/utils.rs index 6148f17e7f17e..864d7e920f81a 100644 --- a/client/cli/src/commands/utils.rs +++ b/client/cli/src/commands/utils.rs @@ -91,17 +91,17 @@ pub fn print_from_uri( }, OutputType::Text => { println!( - "Secret phrase `{}` is account:\n \ + "Secret phrase: {}\n \ Secret seed: {}\n \ Public key (hex): {}\n \ - Public key (SS58): {}\n \ Account ID: {}\n \ + Public key (SS58): {}\n \ SS58 Address: {}", uri, format_seed::(seed), format_public_key::(public_key.clone()), + format_account_id::(public_key.clone()), public_key.to_ss58check_with_version(network_override), - format_account_id::(public_key), pair.public().into().into_account().to_ss58check_with_version(network_override), ); }, @@ -130,14 +130,14 @@ pub fn print_from_uri( "Secret Key URI `{}` is account:\n \ Secret seed: {}\n \ Public key (hex): {}\n \ - Public key (SS58): {}\n \ Account ID: {}\n \ + Public key (SS58): {}\n \ SS58 Address: {}", uri, if let Some(seed) = seed { format_seed::(seed) } else { "n/a".into() }, format_public_key::(public_key.clone()), + format_account_id::(public_key.clone()), public_key.to_ss58check_with_version(network_override), - format_account_id::(public_key), pair.public().into().into_account().to_ss58check_with_version(network_override), ); }, @@ -151,8 +151,8 @@ pub fn print_from_uri( "publicKeyUri": uri, "networkId": String::from(network_override), "publicKey": format_public_key::(public_key.clone()), - "ss58PublicKey": public_key.to_ss58check_with_version(network_override), "accountId": format_account_id::(public_key.clone()), + "ss58PublicKey": public_key.to_ss58check_with_version(network_override), "ss58Address": public_key.to_ss58check_with_version(network_override), }); @@ -166,15 +166,15 @@ pub fn print_from_uri( "Public Key URI `{}` is account:\n \ Network ID/version: {}\n \ Public key (hex): {}\n \ - Public key (SS58): {}\n \ Account ID: {}\n \ + Public key (SS58): {}\n \ SS58 Address: {}", uri, String::from(network_override), format_public_key::(public_key.clone()), - public_key.to_ss58check_with_version(network_override), format_account_id::(public_key.clone()), public_key.to_ss58check_with_version(network_override), + public_key.to_ss58check_with_version(network_override), ); }, } @@ -205,8 +205,8 @@ where let json = json!({ "networkId": String::from(network_override), "publicKey": format_public_key::(public_key.clone()), - "ss58PublicKey": public_key.to_ss58check_with_version(network_override), "accountId": format_account_id::(public_key.clone()), + "ss58PublicKey": public_key.to_ss58check_with_version(network_override), "ss58Address": public_key.to_ss58check_with_version(network_override), }); @@ -216,14 +216,14 @@ where println!( "Network ID/version: {}\n \ Public key (hex): {}\n \ - Public key (SS58): {}\n \ Account ID: {}\n \ + Public key (SS58): {}\n \ SS58 Address: {}", String::from(network_override), format_public_key::(public_key.clone()), - public_key.to_ss58check_with_version(network_override), format_account_id::(public_key.clone()), public_key.to_ss58check_with_version(network_override), + public_key.to_ss58check_with_version(network_override), ); }, } diff --git a/client/cli/src/params/keystore_params.rs b/client/cli/src/params/keystore_params.rs index 4eb5e5dc6c2d2..99da21a12f768 100644 --- a/client/cli/src/params/keystore_params.rs +++ b/client/cli/src/params/keystore_params.rs @@ -46,7 +46,8 @@ pub struct KeystoreParams { )] pub password_interactive: bool, - /// Password used by the keystore. + /// Password used by the keystore. This allows appending an extra user-defined secret to the + /// seed. #[structopt( long = "password", parse(try_from_str = secret_string_from_str),