From 8daa756e59a187bdc4d86f6109886cd6d58b799d Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 23 Mar 2021 20:54:28 -0700 Subject: [PATCH 01/13] draft --- docs/migrations/keyring.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/migrations/keyring.md diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md new file mode 100644 index 000000000000..d8c580303edb --- /dev/null +++ b/docs/migrations/keyring.md @@ -0,0 +1,32 @@ +# Keyring Migrate Quick Start + +`keyring` is mechanism of managing private/public keypair in cosmos-sdk. + +The more detailed information about keyring you can find here [here](../run-node/keyring.md) + + +## Backends + +The `keyring` supports the following backends: + +* `os` uses the operating system's default credentials store. +* `file` uses encrypted file-based keystore within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts. +* `kwallet` uses KDE Wallet Manager as a credentials management application. +* `pass` uses the pass command line utility to store and retrieve keys. +* `test` stores keys insecurely to disk. It does not prompt for a password to be unlocked and it should be use only for testing purposes. + + +## CLI command + +Usage: +simd migrate + +Migrates key information from the legacy (db-based) Keybase to the new keyring-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. $HOME/.gaiacli/keys/. For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. + +You can find command implementation [here](../../client/keys/migrate.go) + +## Flags +`FlagDryRun` bool flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes. + + + From 023abd6a039f17c19011e431b70deb9c12044d09 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Wed, 24 Mar 2021 16:06:59 -0700 Subject: [PATCH 02/13] update --- docs/migrations/README.md | 1 + docs/migrations/keyring.md | 37 +++++++++++++++---------------------- 2 files changed, 16 insertions(+), 22 deletions(-) diff --git a/docs/migrations/README.md b/docs/migrations/README.md index 845f661425e4..9b122044ec7b 100644 --- a/docs/migrations/README.md +++ b/docs/migrations/README.md @@ -11,3 +11,4 @@ This folder contains all the migration guides to update your app and modules to 1. [App and Modules Migration](./app_and_modules.md) 1. [Chain Upgrade Guide to v0.40](./chain-upgrade-guide-040.md) 1. [REST Endpoints Migration](./rest.md) +1. [Keyring Migration](./keyring.md) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index d8c580303edb..4a1b7ef70772 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -1,32 +1,25 @@ + # Keyring Migrate Quick Start -`keyring` is mechanism of managing private/public keypair in cosmos-sdk. +`keyring` is mechanism for managing private/public keypair. Cosmos SDK v0.42 (Stargate) introduced some breaking changes in the keyring. Upgrading your chain from <=v0.39 to Stargate requires you to migrate your keys inside the `keyring` to the latest version. For more detailed information about the keyring, you can read [the keyring guide](../run-node/keyring.md) -The more detailed information about keyring you can find here [here](../run-node/keyring.md) +This guide describes how to perform the keyring migration process. +The migration process is handled by the following CLI command: -## Backends +```bash +Usage +simd keys migrate -The `keyring` supports the following backends: +This command migrates key information from the legacy (db-based) Keybase to the new [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). +For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. -* `os` uses the operating system's default credentials store. -* `file` uses encrypted file-based keystore within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts. -* `kwallet` uses KDE Wallet Manager as a credentials management application. -* `pass` uses the pass command line utility to store and retrieve keys. -* `test` stores keys insecurely to disk. It does not prompt for a password to be unlocked and it should be use only for testing purposes. - - -## CLI command - -Usage: -simd migrate - -Migrates key information from the legacy (db-based) Keybase to the new keyring-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. $HOME/.gaiacli/keys/. For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. - -You can find command implementation [here](../../client/keys/migrate.go) - -## Flags -`FlagDryRun` bool flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes. +The `migrate` CLI commands takes the following flags: +- `--dry-run` boolean flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. +- `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). + From 56052b7657522520d853cddb14e857a664081482 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Mon, 29 Mar 2021 14:29:43 -0700 Subject: [PATCH 03/13] address comments, ready for review --- docs/migrations/keyring.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 4a1b7ef70772..75fd62fc73c1 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -3,7 +3,7 @@ order: 4 --> # Keyring Migrate Quick Start -`keyring` is mechanism for managing private/public keypair. Cosmos SDK v0.42 (Stargate) introduced some breaking changes in the keyring. Upgrading your chain from <=v0.39 to Stargate requires you to migrate your keys inside the `keyring` to the latest version. For more detailed information about the keyring, you can read [the keyring guide](../run-node/keyring.md) +`keyring` is the SDK's mechanism for managing private/public keypair. Cosmos SDK v0.42 (Stargate) introduced some breaking changes in the keyring. Upgrading your chain from <=v0.39 to Stargate requires you to migrate your keys inside the `keyring` to the latest version. For more detailed information about the keyring, you can read [the keyring guide](../run-node/keyring.md) This guide describes how to perform the keyring migration process. @@ -12,13 +12,14 @@ The migration process is handled by the following CLI command: ```bash Usage simd keys migrate +``` -This command migrates key information from the legacy (db-based) Keybase to the new [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). -For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. +This command migrates key information from the legacy (db-based) Keybase to the new [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application home directory **old_home_dir**, e.g. `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). +For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. The `migrate` CLI commands takes the following flags: -- `--dry-run` boolean flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. +- `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. - `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). From e009385ee201b3620d4d80577cb02e5006dd8d19 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Mon, 29 Mar 2021 14:32:52 -0700 Subject: [PATCH 04/13] delete thr last line --- docs/migrations/keyring.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 75fd62fc73c1..a381368e29a6 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -21,6 +21,4 @@ For each key material entry, the command will prompt if the key should be skippe The `migrate` CLI commands takes the following flags: - `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. - `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). - - From 85297dfec82e8818e1a5da19e648c5cf57aa0667 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:32:57 -0700 Subject: [PATCH 05/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index a381368e29a6..8cfcec6e335a 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -3,7 +3,9 @@ order: 4 --> # Keyring Migrate Quick Start -`keyring` is the SDK's mechanism for managing private/public keypair. Cosmos SDK v0.42 (Stargate) introduced some breaking changes in the keyring. Upgrading your chain from <=v0.39 to Stargate requires you to migrate your keys inside the `keyring` to the latest version. For more detailed information about the keyring, you can read [the keyring guide](../run-node/keyring.md) +`keyring` is the Cosmos SDK mechanism to manage the public/private keypair. Cosmos SDK v0.42 (Stargate) introduced breaking changes in the keyring. + +To upgrade your chain from v0.39 and earlier (Launchpad) to Stargate, you must migrate your keys inside the keyring to the latest version. For details on configuring and using the keyring, see [Setting up the keyring](../run-node/keyring.md). This guide describes how to perform the keyring migration process. @@ -21,4 +23,3 @@ For each key material entry, the command will prompt if the key should be skippe The `migrate` CLI commands takes the following flags: - `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. - `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). - From 5c5bb1d51c563a236d8c83f8bc3afec37fe1a4ee Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:33:14 -0700 Subject: [PATCH 06/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 8cfcec6e335a..95a8c9280299 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -16,7 +16,7 @@ Usage simd keys migrate ``` -This command migrates key information from the legacy (db-based) Keybase to the new [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application home directory **old_home_dir**, e.g. `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). +The migration process moves key information from the legacy db-based Keybase to the [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase persists keys in a LevelDB database in a 'keys' sub-directory of the client application home directory (`old_home_dir`). For example, `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. From 6724b1aa4eaad6a1026bd3aab13a4c71e580bf93 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:33:29 -0700 Subject: [PATCH 07/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 95a8c9280299..94ce48249f6f 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -7,7 +7,7 @@ order: 4 To upgrade your chain from v0.39 and earlier (Launchpad) to Stargate, you must migrate your keys inside the keyring to the latest version. For details on configuring and using the keyring, see [Setting up the keyring](../run-node/keyring.md). -This guide describes how to perform the keyring migration process. +This guide describes how to migrate your keyrings. The migration process is handled by the following CLI command: From ae849a0dd481b141a5a82458c141d12514c4dac4 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:33:49 -0700 Subject: [PATCH 08/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 94ce48249f6f..050c143de0cb 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -9,7 +9,7 @@ To upgrade your chain from v0.39 and earlier (Launchpad) to Stargate, you must m This guide describes how to migrate your keyrings. -The migration process is handled by the following CLI command: +The following command migrates your keyrings: ```bash Usage From 4464c21a5311e46baf45fa7f7ef14405745a9eb1 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:34:16 -0700 Subject: [PATCH 09/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 050c143de0cb..52285a5bd8c9 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -18,7 +18,7 @@ simd keys migrate The migration process moves key information from the legacy db-based Keybase to the [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase persists keys in a LevelDB database in a 'keys' sub-directory of the client application home directory (`old_home_dir`). For example, `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). -For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated. +You can migrate or skip the migration for each key entry found in the specified `old_home_dir` directory. Each key migration requires a valid passphrase. If an invalid passphrase is entered, the command exits. Run the command again to restart the keyring migration. The `migrate` CLI commands takes the following flags: - `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. From a77f5e0445903da8a2d8eccbffb0b7603b064564 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:34:32 -0700 Subject: [PATCH 10/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 52285a5bd8c9..331ebb000dc7 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -20,6 +20,6 @@ The migration process moves key information from the legacy db-based Keybase to You can migrate or skip the migration for each key entry found in the specified `old_home_dir` directory. Each key migration requires a valid passphrase. If an invalid passphrase is entered, the command exits. Run the command again to restart the keyring migration. -The `migrate` CLI commands takes the following flags: +The `migrate` command takes the following flags: - `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. - `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). From c354edb31fef8933ece6b7ea974d736e14d716b0 Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 12:39:05 -0700 Subject: [PATCH 11/13] Update docs/migrations/keyring.md Co-authored-by: Barrie Byron --- docs/migrations/keyring.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 331ebb000dc7..e3157fbf4962 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -21,5 +21,11 @@ The migration process moves key information from the legacy db-based Keybase to You can migrate or skip the migration for each key entry found in the specified `old_home_dir` directory. Each key migration requires a valid passphrase. If an invalid passphrase is entered, the command exits. Run the command again to restart the keyring migration. The `migrate` command takes the following flags: -- `--dry-run` boolean flag. If it is set to false, it runs the migration without actually persisting any changes to the new Keybase. If it is set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently. +- `--dry-run` boolean + + - false - run the migration but do not persist changes to the new Keybase. + - true - run the migration and persist keys to the new Keybase. + +Recommended: Use `--dry-run true` to test the migration without persisting changes before you migrate and persist keys. + - `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md). From f047e2c8a32404ba83b00bd8d515203deea142be Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Tue, 6 Apr 2021 18:24:33 -0700 Subject: [PATCH 12/13] ready for review --- docs/migrations/keyring.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index e3157fbf4962..1ab5d60a55d0 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -23,8 +23,8 @@ You can migrate or skip the migration for each key entry found in the specified The `migrate` command takes the following flags: - `--dry-run` boolean - - false - run the migration but do not persist changes to the new Keybase. - - true - run the migration and persist keys to the new Keybase. + - true - run the migration but do not persist changes to the new Keybase. + - false - run the migration and persist keys to the new Keybase. Recommended: Use `--dry-run true` to test the migration without persisting changes before you migrate and persist keys. From 3c0f5e6975e341fb43e72c724aa8422da0c13dbe Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Wed, 7 Apr 2021 11:21:20 -0700 Subject: [PATCH 13/13] Update docs/migrations/keyring.md Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> --- docs/migrations/keyring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md index 1ab5d60a55d0..dbd51269b600 100644 --- a/docs/migrations/keyring.md +++ b/docs/migrations/keyring.md @@ -5,7 +5,7 @@ order: 4 `keyring` is the Cosmos SDK mechanism to manage the public/private keypair. Cosmos SDK v0.42 (Stargate) introduced breaking changes in the keyring. -To upgrade your chain from v0.39 and earlier (Launchpad) to Stargate, you must migrate your keys inside the keyring to the latest version. For details on configuring and using the keyring, see [Setting up the keyring](../run-node/keyring.md). +To upgrade your chain from v0.39 (Launchpad) and earlier to Stargate, you must migrate your keys inside the keyring to the latest version. For details on configuring and using the keyring, see [Setting up the keyring](../run-node/keyring.md). This guide describes how to migrate your keyrings.