pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-30 20:07:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: subkey documentation (#9639)

Browse Source 
* 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 <gilescope@gmail.com>
Co-authored-by: David <dvdplm@gmail.com>
This commit is contained in:
Chevdor
2021-08-31 15:24:37 +02:00
committed by GitHub
parent 6c8946ae21
commit 6c2d9566df
5 changed files with 246 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/bin/utils/subkey/README.adoc
-91
View File
@@ -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 <mnemonic,seed,pubkey,address>
```
_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 <msg> | subkey sign --suri <seed,mnemonic>
```
_Example Output_:
```
a69da4a6ccbf81dbbbfad235fa12cf8528c18012b991ae89214de8d20d29c1280576ced6eb38b7406d1b7e03231df6dd4a5257546ddad13259356e1c3adfb509
```
=== Verifying a signature
```bash
echo -n <msg> | subkey verify <sig> <address>
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 <call-as-hex> \
--nonce 0 \
--suri <secret-uri> \
--password <password> \
--prior-block-hash <prior-block-hash-as-hex>
```
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
```
substrate/bin/utils/subkey/README.md
+208 -1
View File
@@ -1 +1,208 @@
License: GPL-3.0-or-later WITH Classpath-exception-2.0
# 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 <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 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
substrate/bin/utils/subkey/SECURITY.md
+25
View File
@@ -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.
substrate/client/cli/src/commands/utils.rs
+11 -11
View File
@@ -91,17 +91,17 @@ pub fn print_from_uri<Pair>(
},
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::<Pair>(seed),
format_public_key::<Pair>(public_key.clone()),
format_account_id::<Pair>(public_key.clone()),
public_key.to_ss58check_with_version(network_override),
format_account_id::<Pair>(public_key),
pair.public().into().into_account().to_ss58check_with_version(network_override),
);
},
@@ -130,14 +130,14 @@ pub fn print_from_uri<Pair>(
"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::<Pair>(seed) } else { "n/a".into() },
format_public_key::<Pair>(public_key.clone()),
format_account_id::<Pair>(public_key.clone()),
public_key.to_ss58check_with_version(network_override),
format_account_id::<Pair>(public_key),
pair.public().into().into_account().to_ss58check_with_version(network_override),
);
},
@@ -151,8 +151,8 @@ pub fn print_from_uri<Pair>(
"publicKeyUri": uri,
"networkId": String::from(network_override),
"publicKey": format_public_key::<Pair>(public_key.clone()),
"ss58PublicKey": public_key.to_ss58check_with_version(network_override),
"accountId": format_account_id::<Pair>(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<Pair>(
"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::<Pair>(public_key.clone()),
public_key.to_ss58check_with_version(network_override),
format_account_id::<Pair>(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::<Pair>(public_key.clone()),
"ss58PublicKey": public_key.to_ss58check_with_version(network_override),
"accountId": format_account_id::<Pair>(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::<Pair>(public_key.clone()),
public_key.to_ss58check_with_version(network_override),
format_account_id::<Pair>(public_key.clone()),
public_key.to_ss58check_with_version(network_override),
public_key.to_ss58check_with_version(network_override),
);
},
}
substrate/client/cli/src/params/keystore_params.rs
+2 -1
View File
@@ -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),