Skip to main content

Reset OS Keyring Passphrase

TL;DR: With the os keyring backend, rename ~/.zigchain/keyhash after you delete the last os key. The next zigchaind keys add with --keyring-backend os prompts for a new passphrase.

Overview​

A reset OS keyring passphrase clears stored passphrase state when the os keyring has no keys left. You use zigchaind keys on the node; the os backend uses secure storage with a passphrase, while test does not. This guide lists common key commands, then the keyhash rename steps to reset the OS keyring passphrase without touching config or data.

Key Concepts​

  • OS keyring backend: OS secure storage; requires a passphrase per operation.
  • Test keyring backend: Local storage without a passphrase prompt.
  • Keyring passphrase: Secret you set on first use of the os backend; the system stores it for later prompts.
  • keyhash file: Stores the passphrase hash under ~/.zigchain/; renaming it forces a new passphrase setup.
  • zigchaind keys: CLI for add, delete, list, recover, and help.

Key management operations​

Using the zigchaind keys command, you can perform various key management operations. For example:

  1. Recover an account named test_user from a mnemonic, storing the key in the test keyring backend, which does not require a passphrase:
zigchaind keys add test_user --recover --keyring-backend test
  1. Delete test_user's key from the os keyring backend, which uses the operating system's secure storage and does require a passphrase:
zigchaind keys delete test_user --keyring-backend os
  1. List all keys stored on the default keyring backend, which is test:
zigchaind keys list
  1. Explore additional operations:
zigchaind keys --help

Reset OS Keyring Passphrase on the Node​

When you interact with the os keyring backend for the first time—such as when creating or recovering your first key—you will be prompted to set a keyring passphrase by entering it twice:

zigchaind keys add test_user --recover --keyring-backend os
> Enter your bip39 mnemonic
several words without meaning…
Enter keyring passphrase (attempt 1/3):
Re-enter keyring passphrase:

This passphrase will be stored by the system and required for any future operations using the same keyring backend.

Later on, if you delete the last key stored in the os keyring backend, you might want to reset the passphrase—especially if you plan to add keys again in the future.

zigchaind keys delete test_user --keyring-backend os
Enter keyring passphrase (attempt 1/3):
Key reference will be deleted. Continue? [y/N]: y
Key deleted forever (uh oh!)
zigchaind keys list --keyring-backend os
No records were found in keyring

Steps to reset the keyring passphrase​

To reset the OS keyring passphrase, rename keyhash after the os store is empty:

  1. Locate the keyhash file under the ~/.zigchain/ directory:
ls ~/.zigchain/
config  data  keyhash  keyring-test  wasm
  1. Rename the keyhash file (to effectively reset the “os” backend keyring passphrase):
mv ~/.zigchain/keyhash ~/.zigchain/keyhash.old
user@node:~$ ls ~/.zigchain/
config  data  keyhash.old  keyring-test  wasm

Once this is done, the next time you attempt to add a new key using the os backend, you will be prompted to set a new keyring passphrase.

Common Questions​

Why reset the OS keyring passphrase after deleting all keys?​

When no keys remain in the os backend, renaming keyhash clears the old passphrase state. The next zigchaind keys add with --keyring-backend os asks for a new passphrase. You still need the current passphrase to delete the last key; confirm the store is empty with zigchaind keys list --keyring-backend os before you rename the file.

Does resetting the OS keyring passphrase affect the test backend?​

No. test and os are separate stores. A keyhash rename only affects the os backend. Use --keyring-backend on each command to pick the right store.