Skip to content

change-password.md

Latest commit

 

History

History
58 lines (38 loc) · 3.01 KB

change-password.md

File metadata and controls

58 lines (38 loc) · 3.01 KB
Raw

wallet-cli change-password

Change the master password (re-encrypt all software wallet keystores).

Synopsis

wallet-cli change-password [--yes]

Description

The master password decrypts every software wallet's keystore, so changing it means: verify the old password, set a new one, then decrypt-and-re-encrypt every software keystore atomically. Ledger and watch-only accounts hold no secrets and are unaffected.

Interactive-only: old password, new password, and confirmation are all hidden TTY prompts. There is no stdin or argv path — the command handles two high-value secrets at once and runs rarely, so nothing may pass through pipes, shell history, or the process list. Without a TTY it fails with tty_required.

The flow:

  1. Verify — enter the current master password; it must decrypt an existing keystore (auth_failed otherwise, nothing touched).
  2. Set — enter the new password twice. A mismatch or a policy failure is rejected at the prompt and asked again.
  3. Confirm — the command lists how many software wallets will be re-encrypted; [y/N] (skipped with --yes). Declining aborts with no changes.
  4. Re-encrypt — decrypt each keystore with the old password, encrypt with the new one, and stage the files with the password verifier. A journal records the commit point. Before it, a failure reports io_error and the old password remains valid. After it, the new password is in effect; an incomplete replacement reports io_error, and the next wallet command finishes it. Interrupted staging is cleaned up by the next wallet command.

Options

Option Description
--yes Skip the final confirmation prompt (step 3)

Plus the global options.

Examples

wallet-cli change-password
? Master password (hidden):
? New master password (hidden):
? Confirm new password:
? Re-encrypt 3 software wallet(s) with the new password? [y/N]: y
✅ Master password changed — re-encrypted 3 software wallet(s)
  Wallets  wallet1, wallet2, imported-1
  Note     Ledger / watch-only accounts are unaffected

Output

This command is interactive. In text mode the receipt lists the re-encrypted software wallets and never includes secret material. In JSON mode, data.wallets carries those wallet labels/ids and data.count their number. Local command — no chain block.

Exit status

0 changed · 1 execution failure (aborted — Ctrl-C at a prompt; nothing is changed; auth_failed; no_software_wallet — nothing to re-encrypt; invalid_value — a referenced encrypted wallet blob is missing; io_error — the message states whether the old or new password is in effect) · 2 usage error (tty_required — no TTY for interactive input; invalid_value — the new password equals the current one; aborted — confirmation declined).

See also

backup · Security model · machine-interface → Secret handling