Chapter 9 — Data security in the cloud: KMS and envelope encryption

Practice (60 min) — sandbox

1. Create two customer CMKs (tenant-a, tenant-b) with tight key policies (usable only by a specific role, only with a matching tenant encryption context).
2. Write a small script: GenerateDataKey under tenant-a, AES-GCM-encrypt a file with the plaintext DEK, store EncryptedDEK||nonce||ct||tag, zero the DEK. Then decrypt it back.
3. Try to kms:Decrypt the tenant-a blob using a role only allowed on tenant-b — confirm AccessDenied. Try with the wrong encryption context — confirm denial.
4. ScheduleKeyDeletion on tenant-a (min 7-day window; then CancelKeyDeletion before it fires so you don't lose the lab). Read the CloudTrail events.
5. Enforce S3 SSE-KMS with a bucket policy that denies puts without your CMK id; try a plain PutObject and confirm denial.
6. Check CloudTrail: every Decrypt/GenerateDataKey with principal, key, encryption context. This is your data-access audit trail.

Build it in Go (45 min) — envelope encryption with a local "KMS"

The practice above uses a real cloud KMS. This lab builds the same pattern locally, so every mechanism is visible: a KMS whose key material never leaves it, a key policy (caller + tenant), the encryption context bound as AES-GCM additional authenticated data, key versions for rotation, and crypto-shredding.

// envelope: Chapter 9's envelope encryption, end to end, with a tiny local
// "KMS" so you can run it without a cloud account. Everything a real KMS
// enforces is here in miniature: keys that never leave the service, a key
// policy, encryption context bound as AAD, rotation, and crypto-shredding.
//
//	go run ./envelope
package main

import (
	"bytes"
	"crypto/aes"
	"crypto/cipher"
	"crypto/rand"
	"encoding/json"
	"errors"
	"fmt"
	"maps"
	"slices"
	"strings"
)

// ---------------------------------------------------------------- the KMS --

type kmsKey struct {
	versions      [][]byte // key material; never returned to callers
	allowedCaller string   // the key policy, reduced to its essence
	tenant        string   // required encryption context
	deleted       bool
}

type KMS struct{ keys map[string]*kmsKey }

var errAccessDenied = errors.New("AccessDenied")

func (k *KMS) CreateKey(id, caller, tenant string) {
	k.keys[id] = &kmsKey{versions: [][]byte{random(32)}, allowedCaller: caller, tenant: tenant}
}

// authorize is the key policy: right caller AND matching encryption context.
func (k *KMS) authorize(id, caller string, ctx map[string]string) (*kmsKey, error) {
	key, ok := k.keys[id]
	if !ok || key.deleted {
		return nil, fmt.Errorf("key %s: not found or scheduled for deletion", id)
	}
	if caller != key.allowedCaller || ctx["tenant"] != key.tenant {
		fmt.Printf("    [audit] DENY  caller=%s key=%s context=%v\n", caller, id, ctx)
		return nil, errAccessDenied
	}
	fmt.Printf("    [audit] ALLOW caller=%s key=%s context=%v\n", caller, id, ctx)
	return key, nil
}

// GenerateDataKey returns a fresh DEK in plaintext AND wrapped (encrypted
// under the KMS key's newest version, with the context as AAD).
func (k *KMS) GenerateDataKey(id, caller string, ctx map[string]string) (dek, wrapped []byte, err error) {
	key, err := k.authorize(id, caller, ctx)
	if err != nil {
		return nil, nil, err
	}
	dek = random(32)
	v := len(key.versions) - 1
	wrapped = append([]byte{byte(v)}, seal(key.versions[v], dek, aad(ctx))...)
	return dek, wrapped, nil
}

func (k *KMS) Decrypt(id, caller string, wrapped []byte, ctx map[string]string) ([]byte, error) {
	key, err := k.authorize(id, caller, ctx)
	if err != nil {
		return nil, err
	}
	v := int(wrapped[0]) // which key version wrapped this DEK
	if v >= len(key.versions) {
		return nil, errors.New("unknown key version")
	}
	return open(key.versions[v], wrapped[1:], aad(ctx))
}

// Rotate adds a new key version. Old versions stay, so old data still decrypts.
func (k *KMS) Rotate(id string) { k.keys[id].versions = append(k.keys[id].versions, random(32)) }

// ScheduleDeletion = crypto-shredding: every DEK this key wrapped becomes useless.
func (k *KMS) ScheduleDeletion(id string) { k.keys[id].deleted = true; k.keys[id].versions = nil }

// ------------------------------------------------------------ the app side --

// blob is what gets stored: wrapped DEK + nonce + ciphertext + tag. The
// plaintext DEK is never stored.
type blob struct {
	KeyID      string
	WrappedDEK []byte
	Ciphertext []byte // nonce || ciphertext || tag
	Context    map[string]string
}

func encryptObject(kms *KMS, keyID, caller string, ctx map[string]string, plaintext []byte) (*blob, error) {
	dek, wrapped, err := kms.GenerateDataKey(keyID, caller, ctx)
	if err != nil {
		return nil, err
	}
	defer clear(dek) // best effort: zero the plaintext key when done
	return &blob{keyID, wrapped, seal(dek, plaintext, aad(ctx)), ctx}, nil
}

func decryptObject(kms *KMS, caller string, b *blob, ctx map[string]string) ([]byte, error) {
	dek, err := kms.Decrypt(b.KeyID, caller, b.WrappedDEK, ctx)
	if err != nil {
		return nil, err
	}
	defer clear(dek)
	return open(dek, b.Ciphertext, aad(ctx))
}

// ------------------------------------------------------------- primitives --

func seal(key, plaintext, aad []byte) []byte {
	block, _ := aes.NewCipher(key)
	gcm, _ := cipher.NewGCM(block)
	nonce := random(gcm.NonceSize()) // random 96-bit nonce: fine for < 2^32 messages per key
	return gcm.Seal(nonce, nonce, plaintext, aad)
}

func open(key, sealed, aad []byte) ([]byte, error) {
	block, _ := aes.NewCipher(key)
	gcm, _ := cipher.NewGCM(block)
	if len(sealed) < gcm.NonceSize() {
		return nil, errors.New("ciphertext too short")
	}
	return gcm.Open(nil, sealed[:gcm.NonceSize()], sealed[gcm.NonceSize():], aad)
}

// aad turns the encryption context into stable bytes (sorted keys).
func aad(ctx map[string]string) []byte {
	keys := slices.Sorted(maps.Keys(ctx))
	ordered := make([][2]string, len(keys))
	for i, k := range keys {
		ordered[i] = [2]string{k, ctx[k]}
	}
	b, _ := json.Marshal(ordered)
	return b
}

func random(n int) []byte {
	b := make([]byte, n)
	rand.Read(b)
	return b
}

// ------------------------------------------------------------------- demo --

func main() {
	kms := &KMS{keys: map[string]*kmsKey{}}
	kms.CreateKey("tenant-42-key", "data-service", "42")
	kms.CreateKey("tenant-99-key", "data-service", "99")
	invoice := []byte(`{"tenant":42,"total":"129.00","card":"**** 4242"}`)
	ctx42 := map[string]string{"tenant": "42", "purpose": "invoice"}

	step := func(s string) { fmt.Println("\n" + s) }

	step("1. encrypt tenant 42's invoice")
	b, err := encryptObject(kms, "tenant-42-key", "data-service", ctx42, invoice)
	must(err)
	fmt.Printf("    stored: wrappedDEK=%d bytes, ciphertext=%d bytes, plaintext DEK stored: no\n",
		len(b.WrappedDEK), len(b.Ciphertext))

	step("2. decrypt as data-service with the right context")
	pt, err := decryptObject(kms, "data-service", b, ctx42)
	fmt.Printf("    -> %s (err=%v)\n", pt, err)

	step("3. analytics-service tries the same blob (has the bytes, not the key policy)")
	_, err = decryptObject(kms, "analytics-service", b, ctx42)
	fmt.Println("    ->", err)

	step("4. data-service presents the blob with tenant 99's context")
	_, err = decryptObject(kms, "data-service", b, map[string]string{"tenant": "99", "purpose": "invoice"})
	fmt.Println("    ->", err)

	step("5. right caller and tenant, but a different purpose: the AAD no longer matches")
	_, err = decryptObject(kms, "data-service", b, map[string]string{"tenant": "42", "purpose": "export"})
	fmt.Println("    ->", err)

	step("6. tamper with one ciphertext byte")
	tampered := *b
	tampered.Ciphertext = bytes.Clone(b.Ciphertext)
	tampered.Ciphertext[20] ^= 1
	_, err = decryptObject(kms, "data-service", &tampered, ctx42)
	fmt.Println("    ->", err)

	step("7. rotate the KMS key; old data still decrypts, new data uses v2")
	kms.Rotate("tenant-42-key")
	b2, _ := encryptObject(kms, "tenant-42-key", "data-service", ctx42, []byte("new invoice"))
	fmt.Printf("    old blob wrapped with key v%d, new blob with key v%d\n", b.WrappedDEK[0]+1, b2.WrappedDEK[0]+1)
	pt, err = decryptObject(kms, "data-service", b, ctx42)
	fmt.Printf("    old blob -> %s (err=%v)\n", strings.TrimSpace(string(pt[:20])), err)

	step("8. tenant 42 leaves: crypto-shred by deleting their key")
	kms.ScheduleDeletion("tenant-42-key")
	_, err = decryptObject(kms, "data-service", b, ctx42)
	fmt.Println("    ->", err, "\n    every copy of every blob (backups, replicas, exports) is now unreadable")
}

func must(err error) {
	if err != nil {
		panic(err)
	}
}

$ go run ./envelope
1. encrypt tenant 42's invoice
    [audit] ALLOW caller=data-service key=tenant-42-key context=map[purpose:invoice tenant:42]
    stored: wrappedDEK=61 bytes, ciphertext=77 bytes, plaintext DEK stored: no
2. decrypt as data-service with the right context
    -> {"tenant":42,"total":"129.00","card":"**** 4242"} (err=<nil>)
3. analytics-service tries the same blob (has the bytes, not the key policy)
    [audit] DENY  caller=analytics-service key=tenant-42-key ...
    -> AccessDenied
4. data-service presents the blob with tenant 99's context
    -> AccessDenied
5. right caller and tenant, but a different purpose: the AAD no longer matches
    [audit] ALLOW caller=data-service key=tenant-42-key context=map[purpose:export tenant:42]
    -> cipher: message authentication failed
6. tamper with one ciphertext byte
    -> cipher: message authentication failed
7. rotate the KMS key; old data still decrypts, new data uses v2
    old blob wrapped with key v1, new blob with key v2
    old blob -> {"tenant":42,"total" (err=<nil>)
8. tenant 42 leaves: crypto-shred by deleting their key
    -> key tenant-42-key: not found or scheduled for deletion

What to notice:

• Step 3 is the worked example above, executed. Having the ciphertext bytes (an S3 read) is worthless without the key policy.
• Step 5 passed the policy check and still failed. The encryption context is authenticated data on the wrapped data key, so a ciphertext encrypted for purpose:invoice can't be unwrapped as purpose:export, even by an authorised caller. That's the "binds a ciphertext to its context" property.
• Rotation keeps old versions. The wrapped key records which key version sealed it (v1), so rotating never breaks old data. Re-wrapping old data keys under v2 is a separate, optional job. Note that the bulk data isn't re-encrypted.
• Use the AWS Encryption SDK or Google Tink in production. This lab is for understanding; those libraries also handle key caching, the message format, and algorithm agility.

Exercises:

1. Add a tokenization vault (Chapter 43): replace card numbers with random tokens and keep the mapping encrypted under its own key.
2. Add per-object data-key caching with a maximum number of uses and a maximum age, then count KMS calls before and after.
3. Write a re-wrap job that moves every stored data key to the newest key version without touching the ciphertexts.