TKM Reference

What is TKM?

Tetra Key Manager manages SSH keys for multi-environment deployments

TKM provides organization-scoped SSH key management with automatic ~/.ssh/config generation. Keys are stored per-org in ~/.ssh// and named by environment and user.

~/.ssh//
  dev_root       # Root key for dev environment
  dev_root.pub
  dev_app        # App user key for dev
  dev_app.pub
  staging_root
  prod_root

Key directory structure

Permission Model

Two-user model: auth_user (login) and work_user (application)

Each environment has two SSH users configured in tetra.toml:

[environments.dev]
host = "192.168.1.100"
ssh_auth_user = "root"     # Login as root
ssh_work_user = "app"      # Deploy as app user

tetra.toml environment configuration

Key Lifecycle

Generate, deploy, rotate, revoke

1. init - Create ~/.ssh// directory
2. generate - Create ED25519 key pairs, update ~/.ssh/config
3. deploy - Push public keys to remote authorized_keys
4. test - Verify SSH connectivity
5. rotate - Revoke old + generate new + deploy (atomic rotation)
6. revoke - Archive keys with timestamp, remove SSH config

Info Commands

Status, diagnostics, and key information

• tkm status Show keys for current org with fingerprints
• tkm doctor Audit setup: org, keys, SSH config, connectivity
• tkm list List key names only (no fingerprints)
• tkm test [env|all] Test SSH connectivity to environments
• tkm fingerprint Show fingerprint for specific key or all keys

Key Operations

Generate, deploy, and manage SSH keys

• tkm init Create ~/.ssh// directory with proper permissions
• tkm gen Generate keys + update SSH config
• tkm deploy Push public keys to remote servers
• tkm deploy --key Deploy using bootstrap key for initial access
• tkm revoke Archive keys with timestamp, remove SSH config
• tkm rotate Full rotation: revoke + generate + deploy

SSH Config

Manage ~/.ssh/config entries

• tkm config Show SSH config entries for current org
• tkm config gen Generate SSH config entries from tetra.toml
• tkm config edit Open ~/.ssh/config in $EDITOR

# tkm: myorg dev
Match Host 192.168.1.100 User root
    IdentityFile ~/.ssh/myorg/dev_root

Match Host 192.168.1.100 User app
    IdentityFile ~/.ssh/myorg/dev_app

Generated SSH config (Match blocks by hostname + user)

Remote Key Management

Manage authorized_keys on remote servers

• tkm remote list [user] List keys with fingerprints
• tkm remote audit [user] Show known/unknown keys (compare to local)
• tkm remote diff [user] Show what's different (to add/remove)
• tkm remote sync [user] Make remote match local keys
• tkm remote add Add a key (checks for duplicates)
• tkm remote rm Remove by index, fingerprint, or pattern
• tkm remote clean Remove all keys matching pattern

Remote commands support flags: -f, --force (skip confirmation), -n, --dry-run (preview changes)

Initial Setup

First-time key setup for a new organization

# 1. Switch to organization
org switch myorg

# 2. Initialize key directory
tkm init
# Created: ~/.ssh/myorg/

# 3. Generate all keys
tkm gen all
# Generates: dev_root, dev_app, staging_root, prod_root
# Updates: ~/.ssh/config with Match blocks

# 4. Deploy keys (needs initial access)
tkm deploy all --key ~/.ssh/id_rsa
# Pushes public keys to authorized_keys

# 5. Verify
tkm test
# Tests SSH connectivity to all environments

Key Rotation

Rotate compromised or expired keys

# Full rotation (revoke + generate + deploy)
tkm rotate dev

# Manual rotation steps:
tkm revoke dev         # Archive old keys
tkm gen dev            # Generate new keys
tkm deploy dev         # Deploy to server

# Revoked keys are archived:
# ~/.ssh/myorg/dev_root.revoked.20241206_143022

Audit & Sync

Keep local and remote keys in sync

# Audit: show known vs unknown keys
tkm remote audit dev root
# [1] [KNOWN]   tkm_dev_root
# [2] [UNKNOWN] user@laptop

# Diff: show what needs to change
tkm remote diff dev root
# Present: dev_root (SHA256:abc...)
# Missing: (none)
# Extra: user@laptop (SHA256:xyz...)

# Sync: make remote match local (dry-run first)
tkm remote sync -n dev root
tkm remote sync dev root

org Module

TKM reads environment config from org module

TKM depends on the org module for organization and environment configuration. The active organization determines where keys are stored.

deploy Module

Deploy uses tkm for SSH connectivity

The deploy module uses TKM-managed keys for remote operations. After tkm deploy, deployment commands work automatically:

# SSH uses tkm keys automatically
ssh root@$dev      # Uses ~/.ssh/myorg/dev_root
ssh app@$dev       # Uses ~/.ssh/myorg/dev_app

# Deploy commands work
deploy push myapp dev
deploy exec dev "systemctl restart myapp"

tetra.toml Configuration

Environment configuration for SSH

[org]
name = "myorg"

[environments.dev]
host = "dev.example.com"
ssh_auth_user = "root"
ssh_work_user = "app"

[environments.staging]
host = "staging.example.com"
ssh_auth_user = "root"
ssh_work_user = "deploy"

[environments.prod]
host = "prod.example.com"
ssh_auth_user = "root"
ssh_work_user = "app"

Full tetra.toml example with SSH configuration

Key Security

Security features and best practices

• ED25519 algorithm - Modern, secure key algorithm
• 600/700 permissions - Private keys 600, .ssh dirs 700
• Organization isolation - Keys stored in ~/.ssh//
• Fingerprint tracking - All operations show fingerprints
• Duplicate detection - Prevents adding same key twice
• Key age monitoring - TView shows key age warnings

Lifecycle Security

Safe key rotation and revocation

• Revocation archives - Old keys moved to .revoked.
• Atomic rotation - tkm rotate does revoke+gen+deploy atomically
• Dry-run mode - Preview changes with -n before applying
• Force flag - Skip confirmations with -f (use carefully)
• Bootstrap keys - Initial deploy finds existing access keys

Auditing

Track and verify key access

Regular auditing helps detect unauthorized keys:

# Check all environments
for env in dev staging prod; do
  echo "=== $env ==="
  tkm remote audit $env root
done

# Remove unknown keys
tkm remote clean dev root 'unknown_*'
tkm remote sync dev root