WIP: Ledger security release docs (2026.1)

[evanorti]

WIP: Ledger security release docs (2026.1)

Documentation for the 2026.1 security release: post-quantum keys (ML-DSA),
zero-downtime consensus key rotation, and remote signing via Cosmos-KMS.
Every technical claim is code- or test-verified before its page merges.

Nav: three groups under Run a Node (SDK next): Key Rotation, Post-quantum Keys,
Remote Signing: Cosmos-KMS.

Key Rotation

• Key rotation — concept: which keys rotate, mechanics, safety rails
• Rotate a consensus key, Staking — test-verified on a localnet
• Rotate a consensus key, PoA — provisional against feat(enterprise/poa): consensus key rotations cosmos-sdk#26590 until merge

Post-quantum Keys

• Post-quantum keys — keys and algorithms survey, ML-DSA, costs, EVM note
• Enable ML-DSA keys — genesis and governance paths; governance flow test-verified
• Migrate a validator to ML-DSA — keygen step blocked on tooling (TODO(ERIC) in page)
• Create an ML-DSA account — test-verified on a localnet

Remote Signing: Cosmos-KMS

• Cosmos-KMS and remote signing (overview)
• Remote signing tutorial — test-verified e2e
• Configure a signing backend (AWS KMS, PKCS#11, file) — AWS/PKCS#11 sections pending execution
• Rotate a consensus key held in Cosmos-KMS — test-verified e2e
• Cosmos-KMS configuration reference
• Remote signing best practices
• Migrate from TMKMS — skeleton; TODO(ERIC) sections pending content

Module references and release-impact fixes

• x/staking README: MsgRotateConsPubKey, KeyRotationFee, rotation stores, End-Block
• PoA api/governance/overview: RotateConsPubKey (provisional until #26590 merges)
• run-production: TMKMS walkthrough replaced with Cosmos-KMS links + deprecation note
• keyring: key algorithms corrected (secp256k1 + ml_dsa_65 via --key-type), new pages linked
• run-node: state-sync-adjacent next steps, link fixes

Upgrading

• 0.53/0.54 → 0.55 upgrade docs — blocked on UPGRADING content (FOU-754)

Verification

Five flows run end to end against local chains, commands exactly as published:
governance param change, staking rotation, ML-DSA account, kms file-backend
tutorial, and kms rotation. Each tested page carries a hidden verification
comment with environment and commits.

• npx mint broken-links clean

Review

• Per-page review issues with instructions live in Linear (Ledger Security Docs
  project, FOU-739 to FOU-755): rotation set → Matt, ML-DSA + kms sets → Eric,
  release notes → Alex. Open eng questions are tracked there, and as TODO(ERIC)/
  TODO(MATT) comments in the pages.

[greptile-apps]

Greptile Summary

This WIP PR adds 14 new documentation pages for the 2026.1 security release, covering post-quantum ML-DSA keys, zero-downtime consensus key rotation (staking and PoA), and Cosmos-KMS remote signing. It also updates existing pages (run-production, keyring, run-node, staking/README, PoA api and overview) to reflect the new release and correct stale content.

• Key rotation (concept + staking + PoA procedures): step-by-step guides are test-verified on a local chain; the PoA page is marked provisional against feat(enterprise/poa): consensus key rotations cosmos-sdk#26590.
• Post-quantum keys (survey, genesis/governance enable, validator migration, user account creation): governance flow and account creation are test-verified; the validator keygen step is a documented TODO pending release tooling.
• Cosmos-KMS remote signing (overview, file-backend tutorial, backend configuration, key rotation, config reference, best practices, TMKMS migration): file-backend tutorial and KMS rotation are verified end-to-end; AWS KMS and PKCS#11 backend sections carry explicit test TODOs; the TMKMS migration guide is a partial skeleton with clearly marked gaps.
• All new pages carry noindex: true and docs.json registration is complete.

Confidence Score: 5/5

Safe to continue reviewing; all changes are documentation only with no executable code paths affected.

Every changed file is an MDX documentation page or a work log entry. The procedural pages that are marked test-verified carry hidden verification comments with environment details. Incomplete sections (TMKMS migration skeleton, AWS/PKCS#11 backend, ML-DSA keygen) are consistently marked with noindex: true and explicit TODO comments, so unfinished content cannot reach readers. The only finding is a style guide violation in poa/api.mdx that follows the pre-existing bold-label pattern of that file and has no reader-facing impact.

sdk/next/kms/migrate-from-tmkms.mdx has three skeleton sections (softsign key format, state migration, YubiHSM) that must be filled before the page can be published. sdk/next/enterprise/poa/api.mdx and sdk/next/keys/rotate-validator-key-poa.mdx are provisional against cosmos/cosmos-sdk#26590 and need re-verification at merge.

Important Files Changed

Filename	Overview
docs.json	Adds three nav groups under Run a Node (Key Rotation, Post-quantum Keys, Remote Signing: Cosmos-KMS) with all 14 new pages correctly registered; no redirects needed since paths are new.
sdk/next/keys/key-rotation.mdx	New concept page explaining consensus key rotation mechanics, safety rails, and PoA vs staking differences; accurate and well-linked. Bold list items flagged in a previous review pass.
sdk/next/keys/rotate-validator-key.mdx	Step-by-step staking rotation guide with test-verified commands, correct state-sync pointer, and appropriate double-sign Danger callout.
sdk/next/keys/post-quantum-keys.mdx	ML-DSA survey page with accurate size/cost numbers and correct EVM/EIP roadmap description; bold Example: previously flagged.
sdk/next/keys/enable-ml-dsa-keys.mdx	Governance-path guide with test-verified jq command for building the consensus param proposal; Warning callout correctly explains the null-field failure mode.
sdk/next/keys/create-ml-dsa-account.mdx	Test-verified ML-DSA account creation guide; content and commands are correct.
sdk/next/kms/tutorial-file-backend.mdx	End-to-end verified tutorial for Cosmos-KMS file backend; correctly documents the signer-first startup requirement and the startup-timeout edge case.
sdk/next/kms/rotate-key-remote-signer.mdx	Test-verified rotation guide for a KMS-held key; Danger callout correctly warns against using show-validator on a remote-signing node.
sdk/next/kms/configuration-reference.mdx	Complete kms.yaml field reference transcribed from config.go; two open TODOs on algorithm default behavior and gRPC TLS requirements are clearly marked.
sdk/next/kms/migrate-from-tmkms.mdx	Skeleton migration guide with correct config mapping table and double-sign Danger callout; softsign key format conversion, state migration, and YubiHSM sections are stubs with explicit TODOs — not yet safe to publish as-is.
sdk/next/enterprise/poa/api.mdx	Adds RotateConsPubKey message reference (provisional against cosmos/cosmos-sdk#26590); new section uses bold labels matching the pre-existing file style but violating the no-bold rule.
sdk/next/node/run-production.mdx	TMKMS walkthrough replaced with concise Cosmos-KMS pointer and TMKMS deprecation Note; clean substitution with correct links.
sdk/next/node/keyring.mdx	Corrects two pre-existing errors: fixes broken in-page anchor and updates key algorithm list to match the actual keyring source (secp256k1 + ml_dsa_65, removing the stale ed25519/--algo claim).
sdk/next/kms/best-practices.mdx	Security-oriented placement and transport guide; correctly explains the SecretConnection vs Noise asymmetry and the one-signer-per-key rule with an appropriately loud Danger callout.
work-log/security-release.md	Work log for the branch; entries follow the required format (date, bullet points, brief descriptions) and are thorough.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Operator submits MsgRotateConsPubKey] --> B[Chain emits power update to CometBFT:
old key → 0, new key → full power]
    B --> C{2 heights pass}
    C --> D[CometBFT activates new key
Chain stores new key]
    D --> E[Shadow node starts signing]
    D --> F[Old node stops signing]
    E --> G[Retire old node / signer]

    subgraph Zero-downtime window
        H[Old node still signing] -.-> C
        I[Shadow node syncing
non-signing full node] -.-> C
    end

    subgraph Remote signer path
        J[New key in KMS backend] --> K[Second kms process
for shadow node]
        K --> I
    end

    subgraph ML-DSA path
        L[Generate ml_dsa_65 key] --> M[Replace priv_validator_key.json
on shadow node]
        M --> I
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Operator submits MsgRotateConsPubKey] --> B[Chain emits power update to CometBFT:
old key → 0, new key → full power]
    B --> C{2 heights pass}
    C --> D[CometBFT activates new key
Chain stores new key]
    D --> E[Shadow node starts signing]
    D --> F[Old node stops signing]
    E --> G[Retire old node / signer]

    subgraph Zero-downtime window
        H[Old node still signing] -.-> C
        I[Shadow node syncing
non-signing full node] -.-> C
    end

    subgraph Remote signer path
        J[New key in KMS backend] --> K[Second kms process
for shadow node]
        K --> I
    end

    subgraph ML-DSA path
        L[Generate ml_dsa_65 key] --> M[Replace priv_validator_key.json
on shadow node]
        M --> I
    end

Loading

_{Reviews (2): Last reviewed commit: "update todos" | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟢 Ready	View Preview	Jul 10, 2026, 7:56 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[evanorti]

@greptileai plz rereview

[Eric-Warehime]

YubiHSM and Fortanix both suppot PKCS#11 so you should be able to configure them using the pkcs11 signer in this repo.

The Ledger signer in tmkms isn't implemented in cosmos/kms. We should call out that it's explicitly out of scope right now and request people to open an issue for a support as a feature request which we will evaluate based on demand going forward.

[Eric-Warehime]

cosmos/kms currently supports either tcp://host:port with no node ID. This would connect using cometbft's custom secret conn for those using cometbft's p2p networking. Or if you are running comet using libp2p, provide noise://<peer-id>@host:port. Note that this only works for those using libp2p peer IDs.

[Eric-Warehime]

The tmkms softsign format is not compatible with cosmos/kms's file signer.

If the tmkms key came from a priv_validator_key.json (tmkms softsign import converts from it), just point the kms key_file at the original json.

Otherwise you'll have to decode the seed from the tmkms file and re-encode it as the kms file expects. There's not support for this in the repo right now, but it should be pretty straightforward to shell script this.

[Eric-Warehime]

Suggested change

	Keys generated inside an HSM are typically non-exportable, which is the point of an HSM. A key that cannot leave the device cannot be moved into AWS KMS or another token. For those keys, migrate by rotation instead: generate a new key in the target custodian and rotate the validator to it on chain, which retires the TMKMS-held key entirely. See [Rotate a consensus key, Staking](/sdk/next/keys/rotate-validator-key).
	Keys generated inside an HSM are typically non-exportable, which is the point of an HSM. A key that cannot leave the device cannot be moved into AWS KMS.
	You can point Cosmos-KMS at existing HSM keys via the same PKCS#11 interface and continuing using them. For keys not falling into this category, you can migrate by rotation instead: generate a new key in the target custodian and rotate the validator to it on chain, which retires the TMKMS-held key entirely. See [Rotate a consensus key, Staking](/sdk/next/keys/rotate-validator-key).

[Eric-Warehime]

Since YubiHSM support PKCS11 you should be able to just wire up the config in cosmos-kms and continue using the same key.

[Eric-Warehime]

It is not the same format.
LLM produces jq '{height, round: (.round|tonumber), step: (.step + 1)}' tmkms_state.json > <home>/state/<chain-id>.json as a one-liner to translate which we can put in the docs if we want.

[Eric-Warehime]

If you try to point kms file signer at a tmkms softsign file you will see: file: parse key file "<path>": expected 64-byte ed25519 key, got 32

If you try to use tcp://node-id@host:port for the connection string you will see dial tcp: lookup node-id@host:port no such host

If you try to re-use the tmkms validator state file you will see chain "<chain-id>": reload sign-state: json: cannot unmarshal string into Go value of type int32

[Eric-Warehime]

Prefer to run the kms binary on a separate host with network firewall since this maximally reduces attack vectors. However, if your validator node is fronted by a sentry node then kms can be run locally as network isolation is already built into the setup. Additionally if cost efficiency is a concern, running both processes on the same host still gives the benefits of remote signing and may be an acceptable tradeoff.

[Eric-Warehime]

I'm not super convinced we should be recommending Horcrux to people.

[Eric-Warehime]

Mandatory tls configuration was removed--it's optional now.

[Eric-Warehime]

Defaults were removed--you need to explicitly configure the algorithm you want to use.

[Eric-Warehime]

It's sufficient to upgrade to 0.55 without doing any additional chain configuration, but you need the entire chain to be running it since a binary built with an older sdk version will not be able to handle mldsa signatures.

[Eric-Warehime]

Maybe it's not deprecated, but we should say we're moving away from it and will be implementing signing support in cosmos/kms going forward.

[Eric-Warehime]

privval supports ed25519, secp256k1eth, and mldsa65

signer service suports ed25519, and secp256k1eth

[Eric-Warehime]

mldsa is supported for file, awskms, and pkcs11 for privval.

[Eric-Warehime]

No defaults exist anymore.

[Eric-Warehime]

yes awskms includes all keytypes that cosmos-kms supports.