Key Rotation

SSH Key Rotation

Understand how SSH-KLM automates key rotation while ensuring zero downtime and full auditability.

Overview

Key rotation is the process of replacing existing SSH keys with new ones. Regular rotation limits the window of exposure if a key is compromised and satisfies compliance requirements.

Rotation Strategies

In-Band Rotation

Key rotation happens through the existing SSH connection.

sequenceDiagram
    participant KLM as SSH-KLM
    participant Agent as Agent
    participant Host as Target Host

    KLM->>KLM: Generate new key pair
    KLM->>Agent: Add new public key
    Agent->>Host: Append to authorized_keys
    KLM->>KLM: Test new key access
    KLM->>Agent: Remove old public key
    Agent->>Host: Update authorized_keys
    KLM->>KLM: Archive old key

Pros: No additional access required Cons: Requires working SSH access

Out-of-Band Rotation

Uses alternative access method (e.g., agent, API, console).

Pros: Works even if SSH access is broken Cons: Requires agent or alternative access

Zero-Downtime Rotation

SSH-KLM ensures continuous access during rotation:

1. Add New Key First - New public key added to authorized_keys
2. Verify Access - Test authentication with new key
3. Remove Old Key - Only after new key is verified
4. Rollback Ready - Old key retained for rollback window

// Configure zero-downtime rotation
await client.ssh.createRotationPolicy({
  name: 'Production Servers',
  strategy: 'zero-downtime',
  verifyBeforeRemove: true,
  rollbackWindow: '24h',
  parallelRotations: 5
});

Rotation Policies

Policy Configuration

const policy = await client.ssh.createRotationPolicy({
  name: 'Standard Rotation',

  // Rotation frequency
  rotationInterval: '90d',  // Every 90 days

  // Key specifications
  algorithm: 'ed25519',  // or 'rsa-4096'

  // Safety settings
  requireApproval: false,
  verifyAccess: true,
  rollbackWindow: '48h',

  // Scheduling
  maintenanceWindow: {
    dayOfWeek: ['saturday', 'sunday'],
    startHour: 2,
    endHour: 6
  },

  // Notifications
  notifyBefore: '7d',
  notifyOnComplete: true,
  notifyOnFailure: true
});

Policy Parameters

Parameter	Description	Recommended
rotationInterval	How often to rotate	90 days
algorithm	Key algorithm	ED25519
requireApproval	Manual approval needed	true (production)
verifyAccess	Test new key before removing old	true
rollbackWindow	Time to keep old key	24-48 hours
maintenanceWindow	When rotation can occur	Off-peak hours

Rotation Workflow

Automated Rotation

flowchart TD
    A[Policy Triggers Rotation] --> B[Generate New Key Pair]
    B --> C{Approval Required?}
    C -->|Yes| D[Wait for Approval]
    C -->|No| E[Deploy New Public Key]
    D --> E
    E --> F[Verify New Key Access]
    F --> G{Access Verified?}
    G -->|Yes| H[Remove Old Key]
    G -->|No| I[Rollback & Alert]
    H --> J[Archive Old Key]
    J --> K[Notify Completion]
    I --> K

Manual Rotation

// Trigger manual rotation for specific key
const rotation = await client.ssh.rotateKey({
  keyId: 'KEY-12345',
  reason: 'Security incident response',
  algorithm: 'ed25519',
  skipApproval: false  // Still require approval
});

// Check rotation status
const status = await client.ssh.getRotationStatus(rotation.id);
console.log(status);
// { status: 'pending_approval', approver: 'security-team' }

Rollback

If rotation fails, SSH-KLM can automatically rollback:

// Manual rollback
await client.ssh.rollbackRotation({
  rotationId: 'ROT-12345',
  reason: 'Application connectivity issues'
});

// Configure automatic rollback
await client.ssh.updateRotationPolicy({
  policyId: 'POL-123',
  autoRollback: true,
  rollbackTriggers: [
    'verification_failed',
    'connection_timeout',
    'application_error'
  ]
});

Rotation for Service Accounts

Service accounts require special handling:

const servicePolicy = await client.ssh.createRotationPolicy({
  name: 'Service Account Rotation',
  targetType: 'service-account',

  // Coordinate with applications
  preRotationHook: 'https://api.example.com/pre-rotation',
  postRotationHook: 'https://api.example.com/post-rotation',

  // Extended verification
  verificationScript: '/opt/scripts/verify-service.sh',
  verificationTimeout: '5m',

  // Conservative rollback
  rollbackWindow: '72h'
});

Examples

Bulk Rotation

// Rotate all keys matching criteria
const bulkRotation = await client.ssh.bulkRotate({
  filter: {
    riskScoreMin: 80,
    algorithm: ['dsa', 'rsa-1024'],
    ageGreaterThan: '365d'
  },
  batchSize: 10,
  delayBetweenBatches: '5m'
});

console.log(`Scheduled ${bulkRotation.totalKeys} keys for rotation`);

Emergency Rotation

// Emergency rotation (skip normal safeguards)
const emergency = await client.ssh.emergencyRotate({
  keyIds: ['KEY-123', 'KEY-456', 'KEY-789'],
  reason: 'Potential key compromise',
  skipMaintenanceWindow: true,
  notifyImmediately: true
});

Troubleshooting

Rotation Stuck in Pending

Issue: Rotation shows “pending” for extended time

Solutions:

1. Check if approval is required
2. Verify agent connectivity
3. Check maintenance window settings

Verification Failed

Issue: New key fails verification

Solutions:

1. Check SSH daemon configuration
2. Verify authorized_keys file permissions
3. Review SSH logs on target host

Rollback Failed

Issue: Cannot rollback to previous key

Solutions:

1. Check rollback window hasn’t expired
2. Verify old key still in archive
3. Manual intervention may be required

Related Pages

• Discovery Concepts
• Ephemeral Keys
• Operations Guide