Key Rotation Guide

Rotate your encryption keys with zero downtime. FreeState atomically re-encrypts all workspace DEKs in a single transaction — state operations continue uninterrupted during the entire rotation.

When to Rotate Keys

• Scheduled rotation: Annually, or per your compliance policy
• After a team member leaves: Rotate if they had KMS access
• Switching to BYOK: Rotation happens automatically during BYOK setup
• After suspected compromise: Immediate rotation recommended
• Compliance requirement: SOC 2, HIPAA, PCI-DSS policies often mandate regular rotation

Rotation Methods

Method 1: Portal UI (Recommended)

1. Navigate to Settings → Encryption
2. Click Rotate Keys
3. Review the rotation plan:
   • Number of workspaces to re-encrypt
   • Estimated completion time
   • New KEK that will be generated
4. Click Confirm Rotation
5. Monitor progress in the rotation modal

Method 2: API

# Rotate to a new FreeState-managed KEK
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/rotate

# Response:
{
  "success": true,
  "message": "Rotated organization KEK",
  "old_kek_id": "arn:aws:kms:us-east-1:...:key/old-key-id",
  "new_kek_id": "arn:aws:kms:us-east-1:...:key/new-key-id",
  "workspaces_rotated": 245,
  "duration": "7.3s",
  "started_at": "2026-01-03T12:00:00Z",
  "completed_at": "2026-01-03T12:00:07Z",
  "errors": []
}

Method 3: Terraform (for BYOK)

# Update the KMS key ARN in your BYOK configuration
# Then trigger rotation via API or Portal
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_kek_id": "arn:aws:kms:us-east-1:...:key/new-byok-key"}' \
  https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/rotate

How Rotation Works

1. Pre-computation (in memory): For each workspace, FreeState decrypts the DEK using the current KEK, then re-encrypts it with the new KEK. This happens entirely in memory before any database write.
2. Atomic transaction: Once all DEKs are re-encrypted in memory, a single database transaction:
   • Inserts the new KEK record
   • Updates the organization's active KEK ID
   • Marks the old KEK as deprecated
   • Updates all workspace DEK records
3. Cache invalidation: The DEK cache is cleared after the transaction commits, ensuring all subsequent operations use the new KEK.
4. Old KEK retention: Deprecated KEKs are retained for 30 days for rollback capability, then scheduled for deletion.

BYOK Key Rotation

If you're using BYOK (Bring Your Own Key), you can rotate in two ways:

Option A: Rotate the AWS KMS Key Itself

AWS KMS supports automatic key rotation. Enable it on your BYOK key:

# Enable automatic annual rotation on your KMS key
aws kms enable-key-rotation --key-id $KEK_ID

# Or via Terraform (set in your freestate-byok/main.tf):
resource "aws_kms_key" "freestate_byok" {
  enable_key_rotation = true  # AWS rotates the key material annually
  # ... other settings
}

When AWS rotates the key material, existing ciphertext remains decryptable — KMS handles this automatically. No action required in FreeState.

Option B: Switch to a New BYOK Key

To replace your BYOK key entirely (e.g., for compliance or after suspected compromise):

1. Create a new KMS key following the BYOK setup guide
2. Navigate to Settings → Encryption → Rotate Keys
3. Select New BYOK key and enter the new key ARN
4. FreeState re-encrypts all DEKs with the new key and deprecates the old one

Verifying Rotation

# Check current encryption status after rotation
curl -H "Authorization: Bearer $TOKEN" \
  https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/status

# The kek_id field will show the new KEK
{
  "organization_id": "11111111-2222-3333-4444-555555555555",
  "encryption_enabled": true,
  "byok_enabled": false,
  "kms_provider": "aws-kms",
  "key_type": "managed",
  "kek_id": "arn:aws:kms:...:key/NEW-key-id"
}

Rotation History and Audit Log

All rotation events are recorded in the encryption audit log, accessible in Portal under Settings → Encryption → Audit Log, or via API:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/audit

# Returns events like:
{
  "entries": [
    {
      "id": "b3b9c9a4-1234-4cde-9876-abcdef012345",
      "timestamp": "2026-01-03T12:00:07Z",
      "operation": "kek_rotated",
      "organization_id": "11111111-2222-3333-4444-555555555555",
      "workspace_id": null,
      "actor": "user@example.com",
      "kek_id": "arn:aws:kms:...:key/NEW-key-id",
      "status": "success",
      "details": {
        "old_kek_id": "arn:aws:kms:...:key/OLD-key-id",
        "new_kek_id": "arn:aws:kms:...:key/NEW-key-id",
        "workspaces_affected": 245
      },
      "error_message": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Troubleshooting

“Rotation failed: partial completion (245/250 workspaces)”

1. Check the rotation log in Portal for the specific failure reason
2. Retry via API:

   curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     https://api.freestate.cloud/api/v1/organizations/$ORG_ID/encryption/rotate

3. If issue persists, contact support@freestate.cloud with your Organization ID and the rotation timestamp

“KMS access denied during rotation”

For BYOK rotations, verify that the new key's policy grants FreeState the same cross-account permissions as your original BYOK key. See the BYOK key policy section.

Compliance Notes

• SOC 2: FreeState's key rotation procedures are covered in the SOC 2 Type II audit report. Request the report from compliance@freestate.cloud.
• HIPAA: HIPAA Security Rule recommends encryption key rotation as part of an access control policy. FreeState rotation satisfies this with a complete audit trail.
• FIPS 140-2: All rotation operations use FIPS 140-2 validated HSMs within the KMS service.