Key Rotation

Use this page to rotate runtime signing keys without breaking verification of previously signed payloads.

Who This Is For

• operators responsible for signing material
• teams rotating keys on a regular security cadence
• developers who need to understand why old public keys remain published

When To Use This

Use key rotation when the active signing key should change but existing signed runtime payloads must remain verifiable.

How It Works

The CLI surface is:

• locksmith keys list
• locksmith keys public
• locksmith keys rotate

Key rotation behavior:

• the keyset file is updated on disk
• a new active key becomes the signer for new runtime responses
• retired public keys remain available through GET /api/v1/system/public-keys

That last point is what keeps verification working for older signed payloads after rotation.

Example

List the keyset:

./bin/locksmith keys list

Print published public keys:

./bin/locksmith keys public

Rotate:

./bin/locksmith keys rotate

After rotation, make sure the running service is using the updated keyset path and verify the published key list from the system endpoint.

Common Mistakes

• deleting retired public keys too early
• rotating the keyset file without ensuring the running service sees the updated file
• assuming runtime verification can hardcode one permanent kid

Related Pages

• Runtime Verification
• Configuration
• API Contract