1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

// === Terraform: Create KMS key with policy ===
 
resource "aws_kms_key" "data_encryption" {
  description             = "CMK for application data encryption"
  deletion_window_in_days = 30
  enable_key_rotation     = true
  
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "Enable IAM User Permissions"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
        }
        Action   = "kms:*"
        Resource = "*"
      },
      {
        Sid    = "Allow application to encrypt/decrypt"
        Effect = "Allow"
        Principal = {
          AWS = aws_iam_role.application.arn
        }
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:GenerateDataKey",
          "kms:GenerateDataKeyWithoutPlaintext",
          "kms:DescribeKey"
        ]
        Resource = "*"
      },
      {
        Sid    = "Allow security team admin access"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${account_id}:role/security-admin"
        }
        Action = [
          "kms:Create*",
          "kms:Describe*",
          "kms:Enable*",
          "kms:List*",
          "kms:Put*",
          "kms:Update*",
          "kms:Revoke*",
          "kms:Disable*",
          "kms:Get*",
          "kms:ScheduleKeyDeletion",
          "kms:CancelKeyDeletion"
        ]
        Resource = "*"
      }
    ]
  })
}
 
// === TypeScript SDK: Envelope encryption ===
 
import { KMSClient, GenerateDataKeyCommand, DecryptCommand } from "@aws-sdk/client-kms";
import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
 
const kms = new KMSClient({ region: "us-east-1" });
const KEY_ID = "arn:aws:kms:us-east-1:123456789:key/abc123";
 
interface EncryptedData {
  encryptedDataKey: Buffer;  // DEK encrypted by KMS
  iv: Buffer;
  ciphertext: Buffer;
  authTag: Buffer;
}
 
async function encryptWithEnvelope(plaintext: Buffer): Promise<EncryptedData> {
  // Generate a data key - KMS returns both plaintext and encrypted versions
  const { Plaintext, CiphertextBlob } = await kms.send(
    new GenerateDataKeyCommand({
      KeyId: KEY_ID,
      KeySpec: "AES_256",
    })
  );
  
  if (!Plaintext || !CiphertextBlob) throw new Error("Failed to generate data key");
  
  // Use the plaintext key to encrypt data locally
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", Plaintext, iv);
  
  const ciphertext = Buffer.concat([
    cipher.update(plaintext),
    cipher.final()
  ]);
  
  const authTag = cipher.getAuthTag();
  
  // Zero out the plaintext key in memory
  Plaintext.fill(0);
  
  return {
    encryptedDataKey: Buffer.from(CiphertextBlob),  // Store this!
    iv,
    ciphertext,
    authTag
  };
}
 
async function decryptWithEnvelope(encrypted: EncryptedData): Promise<Buffer> {
  // Decrypt the data key using KMS
  const { Plaintext } = await kms.send(
    new DecryptCommand({
      CiphertextBlob: encrypted.encryptedDataKey,
    })
  );
  
  if (!Plaintext) throw new Error("Failed to decrypt data key");
  
  // Use the plaintext key to decrypt data locally
  const decipher = createDecipheriv("aes-256-gcm", Plaintext, encrypted.iv);
  decipher.setAuthTag(encrypted.authTag);
  
  const plaintext = Buffer.concat([
    decipher.update(encrypted.ciphertext),
    decipher.final()
  ]);
  
  // Zero out the plaintext key
  Plaintext.fill(0);
  
  return plaintext;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

import { KMSClient, GenerateDataKeyCommand, DecryptCommand, 
         ScheduleKeyDeletionCommand } from "@aws-sdk/client-kms";
 
interface EncryptedRecord {
  id: string;
  keyId: string;              // Which key version encrypted this record
  keyVersion: number;         // Version number for tracking
  encryptedData: Buffer;
  encryptedDek: Buffer;       // DEK encrypted by KMS key
}
 
class KeyRotationManager {
  private kms: KMSClient;
  private currentKeyId: string;
  private currentVersion: number;
  
  constructor(kms: KMSClient, keyId: string, version: number) {
    this.kms = kms;
    this.currentKeyId = keyId;
    this.currentVersion = version;
  }
  
  /**
   * Gradual re-encryption: process records in batches
   * to avoid service disruption
   */
  async reencryptBatch(
    records: EncryptedRecord[],
    batchSize: number = 100
  ): Promise<void> {
    for (let i = 0; i < records.length; i += batchSize) {
      const batch = records.slice(i, i + batchSize);
      
      await Promise.all(
        batch.map(async (record) => {
          // Skip if already on current key version
          if (record.keyVersion >= this.currentVersion) {
            return;
          }
          
          try {
            // Decrypt with old key
            const plaintext = await this.decrypt(record);
            
            // Re-encrypt with new key
            const newRecord = await this.encrypt(plaintext);
            
            // Update in database (atomic operation)
            await this.updateRecord(record.id, newRecord);
            
            console.log(`Re-encrypted record ${record.id}`);
          } catch (error) {
            console.error(`Failed to re-encrypt ${record.id}:`, error);
            // Log for manual remediation; don't fail entire batch
          }
        })
      );
      
      // Pause between batches to reduce load
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
  
  /**
   * Background job for continuous re-encryption
   */
  async runReencryptionJob(db: Database): Promise<void> {
    // Find records encrypted with old key versions
    const oldRecords = await db.query(`
      SELECT * FROM encrypted_data 
      WHERE key_version < $1 
      ORDER BY created_at ASC
      LIMIT 1000
    `, [this.currentVersion]);
    
    if (oldRecords.length === 0) {
      console.log("All records on current key version");
      return;
    }
    
    console.log(`Re-encrypting ${oldRecords.length} records`);
    await this.reencryptBatch(oldRecords);
    
    // Check if all old data is migrated
    const remaining = await db.queryOne(`
      SELECT COUNT(*) FROM encrypted_data WHERE key_version < $1
    `, [this.currentVersion]);
    
    if (remaining.count === 0) {
      console.log("All data migrated to new key version");
      // Safe to disable old key version
      await this.disableOldKeyVersion();
    }
  }
  
  private async disableOldKeyVersion(): Promise<void> {
    // Schedule deletion of old key (with 30-day safety period)
    const oldKeyId = this.getOldKeyId();
    await this.kms.send(new ScheduleKeyDeletionCommand({
      KeyId: oldKeyId,
      PendingWindowInDays: 30,
    }));
    console.log(`Scheduled deletion of old key ${oldKeyId}`);
  }
  
  // ... encrypt, decrypt, updateRecord, getOldKeyId implementations
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

import { split, combine } from 'shamirs-secret-sharing';
 
/**
 * Shamir's Secret Sharing implementation for key escrow.
 * Split a key into N shares where M are required to reconstruct.
 */
 
interface EscrowConfig {
  totalShares: number;      // N: total number of shares to create
  requiredShares: number;   // M: minimum shares needed to reconstruct
}
 
interface EscrowResult {
  shares: Buffer[];
  shareAssignments: ShareAssignment[];
}
 
interface ShareAssignment {
  shareIndex: number;
  custodian: string;
  storageLocation: string;
  verificationHash: string;  // To verify share integrity without revealing it
}
 
async function escrowKey(
  key: Buffer,
  config: EscrowConfig,
  custodians: string[]
): Promise<EscrowResult> {
  if (custodians.length !== config.totalShares) {
    throw new Error("Custodian count must match total shares");
  }
  
  // Split the key using Shamir's Secret Sharing
  const shares = split(key, {
    shares: config.totalShares,
    threshold: config.requiredShares,
  });
  
  // Create assignment records (for tracking, not storage)
  const shareAssignments: ShareAssignment[] = shares.map((share, index) => ({
    shareIndex: index + 1,
    custodian: custodians[index],
    storageLocation: `secure-vault-${index + 1}`,
    verificationHash: hashShare(share),  // Can verify without combining
  }));
  
  // Each share goes to its custodian via secure channel
  // In practice, use hardware tokens, secure ceremonies, etc.
  
  return { shares, shareAssignments };
}
 
async function recoverKey(
  shares: Buffer[],
  requiredShares: number
): Promise<Buffer> {
  if (shares.length < requiredShares) {
    throw new Error(`Need at least ${requiredShares} shares, got ${shares.length}`);
  }
  
  // Reconstruct the original key
  const key = combine(shares.slice(0, requiredShares));
  
  return key;
}
 
// Example: 3-of-5 escrow for master key
async function setupMasterKeyEscrow() {
  const masterKey = await generateMasterKey();  // From HSM
  
  const result = await escrowKey(masterKey, {
    totalShares: 5,
    requiredShares: 3,
  }, [
    "CEO",
    "CFO",
    "CTO",
    "General Counsel",
    "CISO",
  ]);
  
  // Distribute shares securely
  // CEO gets Share 1, stored in CEO's personal vault
  // CFO gets Share 2, stored in finance department safe
  // etc.
  
  // Store assignments (not shares!) for tracking
  await storeEscrowMetadata({
    keyId: "master-key-v1",
    createdAt: new Date(),
    expiresAt: null,
    assignments: result.shareAssignments,
    threshold: 3,
    totalShares: 5,
  });
  
  console.log("Master key escrowed with 3-of-5 threshold");
}