Configure a signing backend

Point Cosmos-KMS at the custodian holding the consensus key: AWS KMS, a PKCS#11 HSM, or a file.

A signing backend is the custodian that holds the validator’s consensus key and signs with it. Cosmos-KMS supports three: AWS KMS, a PKCS#11 hardware module, and a file on disk. The keys block in kms.yaml selects one, and this guide configures each in turn.

Prerequisites

• A running signer and node, which Remote signing tutorial sets up. Only the keys block changes between backends, so everything else from the tutorial runs as is.
• Per backend: the AWS CLI and an AWS account for AWS KMS; your HSM’s tooling plus OpenSC’s pkcs11-tool for PKCS#11, with SoftHSM2 as a local test rig.

The algorithm field is required for all backends.

AWS KMS

AWS Key Management Service (KMS) is a managed service that stores cryptographic keys and signs with them on request. With this backend, the consensus key lives in KMS and never leaves it. The signer calls the KMS Sign API to produce each signature. Credentials come from the standard AWS default chain: environment, shared config, SSO, or an IAM role. No secrets enter kms.yaml.

Provision an Ed25519 signing key, or reuse one:

aws kms create-key --key-spec ECC_NIST_EDWARDS25519 --key-usage SIGN_VERIFY

aws kms create-alias --alias-name alias/validator --target-key-id <key-id>

Then bind it in the keys block:

keys:
  - chain_ids: [my-chain-1]
    backend: awskms
    algorithm: ed25519
    key_id: alias/validator
    region: us-east-1

The key_id accepts a key ID, a full ARN, or an alias. The region and profile fields are optional and fall back to the AWS default chain. The endpoint field exists for LocalStack-style testing only.

PKCS#11

The PKCS#11 backend keeps the consensus key on a hardware security module (HSM) or token and signs on the device through PKCS#11, the standard interface for cryptographic hardware. The key never leaves the module. The signer uses an existing key only, so provision one with your HSM tooling first. For a local test rig, SoftHSM2 works:

softhsm2-util --init-token --free --label validator-token --pin 1234 --so-pin 4321

pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --login --pin 1234 --keypairgen --key-type EC:edwards25519 --label validator --id 01

Then bind it:

keys:
  - chain_ids: [my-chain-1]
    backend: pkcs11
    algorithm: ed25519
    module: /usr/lib/softhsm/libsofthsm2.so
    token_label: validator-token
    key_label: validator
    pin_env: KMS_PIN

The signer enforces three field rules at startup:

• Select the token with exactly one of token_label or slot.
• Select the key with key_label, key_id (the hex CKA_ID), or both.
• Supply the PIN through exactly one of pin, pin_env, or pin_file.

Prefer pin_env or pin_file. An inline pin puts the PIN in the config file.

File

The file backend reads the consensus key from a file on the signer’s disk into memory. It is the development and testing backend. The key sits in plaintext, so it is not production custody. The tutorial covers it end to end:

keys:
  - chain_ids: [my-chain-1]
    backend: file
    algorithm: ed25519
    key_file: priv_validator_key.json

The key_file accepts a CometBFT priv_validator_key.json or a raw base64-encoded private key. The file backend also signs post-quantum consensus keys. Generate the key with simd init <moniker> --consensus-key-algo ml_dsa_65 and bind it:

keys:
  - chain_ids: [my-chain-1]
    backend: file
    algorithm: mldsa65
    key_file: priv_validator_key.json

Verify any backend

Verification is the same regardless of custodian. Start the signer, start the node, and confirm blocks flow, exactly as in the tutorial:

curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height'

Backend problems surface when the signer starts, not when it signs. A wrong PIN, a missing PKCS#11 module, or missing AWS permissions all fail at kms start before any connection is made. Fix the keys block and start the signer again.

What can go wrong

• The signer rejects the config at startup: a missing algorithm, both token_label and slot set, or more than one PIN source. The error names the offending field.
• The signer starts but cannot reach the key: wrong module path, wrong key_id or alias, or AWS credentials that resolve to no permission. These also fail at startup.
• The node exits with a pubkey timeout: the signer is not running or not reachable. Start the signer first. It dials and retries.

Next steps

• Look up any config field, its type, and its constraints. See the configuration reference.
• Run the whole flow once with the file backend. See Remote signing tutorial.
• Move an existing validator onto a key in a new backend by rotation. See Rotate a consensus key held in Cosmos-KMS.