AWS KMS & Encryption

1import { KMSClient, GenerateDataKeyCommand, DecryptCommand } from '@aws-sdk/client-kms';
2import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
3
4const kms = new KMSClient({ region: 'us-east-1' });
5const KEY_ID = 'arn:aws:kms:us-east-1:123456789012:key/mrk-abc123';
6
7// ─── ENCRYPT ─────────────────────────────────────────────────────────────────
8async function encryptLargeData(plaintext) {
9  // 1. Ask KMS for a data key (symmetric AES-256)
10  const { Plaintext: dek, CiphertextBlob: encryptedDek } = await kms.send(
11    new GenerateDataKeyCommand({ KeyId: KEY_ID, KeySpec: 'AES_256' })
12  );
13
14  // 2. Encrypt the data locally with the plaintext DEK
15  const iv = randomBytes(12);                            // 96-bit IV for GCM
16  const cipher = createCipheriv('aes-256-gcm', dek, iv);
17  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
18  const authTag = cipher.getAuthTag();
19
20  // 3. Immediately discard the plaintext DEK
21  dek.fill(0);
22
23  // 4. Store: encrypted payload + encrypted DEK + IV + authTag
24  return {
25    encryptedData: encrypted.toString('base64'),
26    encryptedDek: Buffer.from(encryptedDek).toString('base64'),
27    iv: iv.toString('base64'),
28    authTag: authTag.toString('base64'),
29  };
30}
31
32// ─── DECRYPT ─────────────────────────────────────────────────────────────────
33async function decryptLargeData({ encryptedData, encryptedDek, iv, authTag }) {
34  // 1. Ask KMS to decrypt the encrypted DEK
35  const { Plaintext: dek } = await kms.send(
36    new DecryptCommand({
37      CiphertextBlob: Buffer.from(encryptedDek, 'base64'),
38      KeyId: KEY_ID,        // optional but recommended for extra safety
39    })
40  );
41
42  // 2. Decrypt the data locally
43  const decipher = createDecipheriv(
44    'aes-256-gcm',
45    dek,
46    Buffer.from(iv, 'base64')
47  );
48  decipher.setAuthTag(Buffer.from(authTag, 'base64'));
49  const decrypted = Buffer.concat([
50    decipher.update(Buffer.from(encryptedData, 'base64')),
51    decipher.final(),
52  ]);
53
54  dek.fill(0);  // zero out plaintext DEK
55  return decrypted.toString();
56}

1import {
2  KmsKeyringNode,
3  buildClient,
4  CommitmentPolicy,
5  LocalCryptographicMaterialsCache,
6  CachingMaterialsManager,
7} from '@aws-crypto/client-node';
8
9const { encrypt, decrypt } = buildClient(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
10
11const keyring = new KmsKeyringNode({ generatorKeyId: KEY_ID });
12
13// Cache: reuse DEK for up to 60 seconds or 100 messages, whichever comes first
14const cache = new LocalCryptographicMaterialsCache(100);
15const cachingCMM = new CachingMaterialsManager({
16  backingMaterialsManager: keyring,
17  cache,
18  maxAge: 60_000,          // 60 seconds
19  maxMessagesEncrypted: 100,
20});
21
22const { result } = await encrypt(cachingCMM, 'Hello, cached world!');

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Sid": "Enable IAM policies",
6      "Effect": "Allow",
7      "Principal": { "AWS": "arn:aws:iam::123456789012:root" },
8      "Action": "kms:*",
9      "Resource": "*"
10    },
11    {
12      "Sid": "Allow app role to use the key",
13      "Effect": "Allow",
14      "Principal": { "AWS": "arn:aws:iam::123456789012:role/AppRole" },
15      "Action": ["kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey"],
16      "Resource": "*"
17    },
18    {
19      "Sid": "Allow key admin",
20      "Effect": "Allow",
21      "Principal": { "AWS": "arn:aws:iam::123456789012:role/KeyAdminRole" },
22      "Action": [
23        "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*",
24        "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*",
25        "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource",
26        "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion"
27      ],
28      "Resource": "*"
29    }
30  ]
31}

1# Create a grant — allow a Lambda execution role to decrypt
2aws kms create-grant   --key-id mrk-abc123   --grantee-principal arn:aws:iam::123456789012:role/LambdaRole   --operations Decrypt GenerateDataKey   --name "lambda-access-grant"
3
4# List grants on a key
5aws kms list-grants --key-id mrk-abc123
6
7# Retire a grant (by the grantee)
8aws kms retire-grant --grant-token <token>
9
10# Revoke a grant (by the key admin)
11aws kms revoke-grant --key-id mrk-abc123 --grant-id <id>

1# Enable automatic annual rotation for a CMK
2aws kms enable-key-rotation --key-id mrk-abc123
3
4# Rotate immediately (on-demand) — no downtime, old versions retained
5aws kms rotate-key-on-demand --key-id mrk-abc123
6
7# Check rotation status
8aws kms get-key-rotation-status --key-id mrk-abc123

1# Create a primary MRK
2aws kms create-key   --multi-region   --description "Primary MRK for global app"   --region us-east-1
3
4# Replicate to another region
5aws kms replicate-key   --key-id arn:aws:kms:us-east-1:123456789012:key/mrk-abc123   --replica-region eu-west-1

1# Upload object with SSE-KMS
2aws s3 cp secret.txt s3://my-bucket/secret.txt   --sse aws:kms   --sse-kms-key-id alias/my-key
3
4# Set default bucket encryption to SSE-KMS
5aws s3api put-bucket-encryption   --bucket my-bucket   --server-side-encryption-configuration '{
6    "Rules": [{
7      "ApplyServerSideEncryptionByDefault": {
8        "SSEAlgorithm": "aws:kms",
9        "KMSMasterKeyID": "alias/my-key"
10      },
11      "BucketKeyEnabled": true
12    }]
13  }'

1// Lambda environment variable encryption with CMK
2import { KMSClient, DecryptCommand } from '@aws-sdk/client-kms';
3
4const kms = new KMSClient({});
5
6// Lambda auto-decrypts env vars with the key at startup.
7// For additional client-side decryption (when using your own CMK):
8async function getDecryptedSecret() {
9  const { Plaintext } = await kms.send(new DecryptCommand({
10    CiphertextBlob: Buffer.from(process.env.ENCRYPTED_API_KEY, 'base64'),
11  }));
12  return Buffer.from(Plaintext).toString('utf-8');
13}

1import { KMSClient, SignCommand, VerifyCommand } from '@aws-sdk/client-kms';
2import { createHash } from 'crypto';
3
4const kms = new KMSClient({});
5const SIGNING_KEY_ID = 'alias/my-signing-key';
6
7// Sign a message
8async function signPayload(message) {
9  const messageHash = createHash('sha256').update(message).digest();
10
11  const { Signature } = await kms.send(new SignCommand({
12    KeyId: SIGNING_KEY_ID,
13    Message: messageHash,
14    MessageType: 'DIGEST',
15    SigningAlgorithm: 'ECDSA_SHA_256',
16  }));
17  return Buffer.from(Signature).toString('base64');
18}
19
20// Verify signature (can use public key locally — no KMS call needed)
21async function verifySignature(message, signature) {
22  const messageHash = createHash('sha256').update(message).digest();
23
24  const { SignatureValid } = await kms.send(new VerifyCommand({
25    KeyId: SIGNING_KEY_ID,
26    Message: messageHash,
27    MessageType: 'DIGEST',
28    Signature: Buffer.from(signature, 'base64'),
29    SigningAlgorithm: 'ECDSA_SHA_256',
30  }));
31  return SignatureValid;
32}