You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by ze...@apache.org on 2026/07/16 22:37:20 UTC

(iceberg-go) branch main updated: feat(encryption): add EncryptionManager, KeyManagementClient interfaces + in-memory KMS (#1447)

This is an automated email from the ASF dual-hosted git repository.

zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git


The following commit(s) were added to refs/heads/main by this push:
     new 625d86ed feat(encryption): add EncryptionManager, KeyManagementClient interfaces + in-memory KMS (#1447)
625d86ed is described below

commit 625d86edcfc8b50279a0ae73e14268514e27950a
Author: Hectar <84...@users.noreply.github.com>
AuthorDate: Thu Jul 16 15:37:14 2026 -0700

    feat(encryption): add EncryptionManager, KeyManagementClient interfaces + in-memory KMS (#1447)
---
 encryption/encryption.go      | 180 ++++++++++++++++++++++++++
 encryption/encryption_test.go | 295 ++++++++++++++++++++++++++++++++++++++++++
 encryption/kms.go             | 225 ++++++++++++++++++++++++++++++++
 3 files changed, 700 insertions(+)

diff --git a/encryption/encryption.go b/encryption/encryption.go
new file mode 100644
index 00000000..23190d00
--- /dev/null
+++ b/encryption/encryption.go
@@ -0,0 +1,180 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Package encryption defines interfaces and utilities for Iceberg table
+// encryption. It provides:
+//
+//   - [EncryptionManager] — the central coordination interface for per-file
+//     envelope encryption and decryption.
+//   - [KeyManagementClient] — the interface for KMS backends (wrap/unwrap DEKs).
+//   - [EncryptedInputFile] / [EncryptedOutputFile] — file wrappers that carry
+//     per-file key metadata alongside the data stream.
+//   - [NativeEncryptionInputFile] / [NativeEncryptionOutputFile] — extensions
+//     for format-native encryption (e.g., Parquet column-level encryption).
+//   - [PlaintextEncryptionManager] — a no-op implementation suitable for
+//     unencrypted tables.
+package encryption
+
+import (
+	"context"
+	"errors"
+
+	icebergio "github.com/apache/iceberg-go/io"
+)
+
+var (
+	// ErrKeyIDNotSupported is returned by [PlaintextEncryptionManager.NewEncryptedOutputFile]
+	// when a caller supplies a non-empty keyID. Accepting the keyID but writing
+	// plaintext would fail open: the caller believes the file is encrypted, but
+	// no encryption is actually performed.
+	ErrKeyIDNotSupported = errors.New("encryption: PlaintextEncryptionManager does not support a non-empty keyID; configure a real EncryptionManager")
+
+	// ErrKeyMetadataNotSupported is returned by [PlaintextEncryptionManager.NewDecryptedInputFile]
+	// when a caller supplies non-empty key metadata. Ignoring the metadata and
+	// returning the raw bytes would fail open: the caller would silently read
+	// encrypted bytes as if they were plaintext.
+	ErrKeyMetadataNotSupported = errors.New("encryption: PlaintextEncryptionManager does not support non-empty key metadata; configure a real EncryptionManager")
+)
+
+// EncryptionKeyMetadata is the opaque per-file key metadata blob embedded in
+// manifest entries (DataFile.KeyMetadata, ManifestFile.KeyMetadata) and
+// statistics files (StatisticsFile.KeyMetadata). The encoding is
+// [EncryptionManager]-defined and typically envelopes the wrapped DEK together
+// with any associated authenticated additional data (AAD).
+type EncryptionKeyMetadata []byte
+
+// EncryptedInputFile is a readable file that carries the per-file encryption
+// key metadata required by an [EncryptionManager] to derive the decryption key.
+type EncryptedInputFile interface {
+	icebergio.File
+	// KeyMetadata returns the opaque per-file encryption key metadata.
+	KeyMetadata() EncryptionKeyMetadata
+}
+
+// EncryptedOutputFile is a writable file whose plaintext content is encrypted
+// by the [EncryptionManager]. After the file has been closed, [KeyMetadata]
+// returns the finalized per-file key metadata to embed in the corresponding
+// manifest entry.
+type EncryptedOutputFile interface {
+	icebergio.FileWriter
+	// KeyMetadata returns the finalized per-file encryption key metadata.
+	// The returned value is only guaranteed to be populated after Close has
+	// been called.
+	KeyMetadata() EncryptionKeyMetadata
+}
+
+// NativeEncryptionInputFile extends [EncryptedInputFile] with access to
+// format-native decryption properties (e.g., Parquet FileDecryptionProperties).
+// An [EncryptionManager] may return a NativeEncryptionInputFile from
+// [EncryptionManager.NewDecryptedInputFile] when native-format encryption is
+// in use; callers should type-assert to retrieve the concrete properties.
+type NativeEncryptionInputFile interface {
+	EncryptedInputFile
+	// NativeDecryptionProperties returns format-native decryption properties.
+	// The concrete type is format-specific; callers should type-assert as
+	// needed (e.g., *parquet.FileDecryptionProperties for Parquet files).
+	NativeDecryptionProperties(ctx context.Context) (any, error)
+}
+
+// NativeEncryptionOutputFile extends [EncryptedOutputFile] with access to
+// format-native encryption properties (e.g., Parquet FileEncryptionProperties).
+// An [EncryptionManager] may return a NativeEncryptionOutputFile from
+// [EncryptionManager.NewEncryptedOutputFile] when native-format encryption is
+// in use; callers should type-assert to retrieve the concrete properties.
+type NativeEncryptionOutputFile interface {
+	EncryptedOutputFile
+	// NativeEncryptionProperties returns format-native encryption properties.
+	// The concrete type is format-specific; callers should type-assert as
+	// needed (e.g., *parquet.FileEncryptionProperties for Parquet files).
+	NativeEncryptionProperties(ctx context.Context) (any, error)
+}
+
+// EncryptionManager handles envelope key derivation, file-level encryption,
+// and decryption. It is the central coordination point between the
+// [KeyManagementClient] (key encryption key operations) and the per-file data
+// encryption keys (DEKs).
+//
+// A [PlaintextEncryptionManager] is provided for tables that do not use
+// encryption. Vendors and users can supply custom implementations to integrate
+// with their KMS solutions.
+type EncryptionManager interface {
+	// NewEncryptedOutputFile creates a new encrypted output file.
+	// keyID is the table property encryption.key-id that identifies the key
+	// encryption key (KEK) to use when wrapping the generated DEK.
+	NewEncryptedOutputFile(ctx context.Context, writer icebergio.FileWriter, keyID string) (EncryptedOutputFile, error)
+
+	// NewDecryptedInputFile wraps an existing file for transparent decryption.
+	// keyMetadata is the per-file opaque blob stored in the manifest entry
+	// (DataFile.KeyMetadata or ManifestFile.KeyMetadata).
+	NewDecryptedInputFile(ctx context.Context, file icebergio.File, keyMetadata EncryptionKeyMetadata) (EncryptedInputFile, error)
+}
+
+// PlaintextEncryptionManager is a no-op [EncryptionManager] that passes all
+// data through without any encryption or decryption. It is the default manager
+// used when no KMS is configured or when a table carries no encryption-keys
+// metadata. It fails closed: any call that supplies a non-empty keyID or
+// non-empty key metadata returns an error rather than silently reading or
+// writing plaintext, since doing so could mask a misconfigured encryption
+// setup.
+type PlaintextEncryptionManager struct{}
+
+var _ EncryptionManager = PlaintextEncryptionManager{}
+
+// NewEncryptedOutputFile returns a pass-through [EncryptedOutputFile] that
+// writes data unmodified and returns nil [EncryptionKeyMetadata]. It fails
+// closed: a non-empty keyID indicates the caller expects the file to be
+// encrypted, and returning nil here would silently write plaintext instead,
+// so it returns [ErrKeyIDNotSupported] rather than ignoring the keyID.
+func (PlaintextEncryptionManager) NewEncryptedOutputFile(_ context.Context, writer icebergio.FileWriter, keyID string) (EncryptedOutputFile, error) {
+	if keyID != "" {
+		return nil, ErrKeyIDNotSupported
+	}
+
+	return &plaintextOutputFile{FileWriter: writer}, nil
+}
+
+// NewDecryptedInputFile returns a pass-through [EncryptedInputFile] that reads
+// data unmodified. It fails closed: non-empty keyMetadata indicates the
+// underlying bytes were encrypted, and returning them unchanged would
+// silently hand ciphertext to the caller as if it were plaintext, so it
+// returns [ErrKeyMetadataNotSupported] rather than ignoring the metadata.
+func (PlaintextEncryptionManager) NewDecryptedInputFile(_ context.Context, file icebergio.File, keyMetadata EncryptionKeyMetadata) (EncryptedInputFile, error) {
+	if len(keyMetadata) != 0 {
+		return nil, ErrKeyMetadataNotSupported
+	}
+
+	return &plaintextInputFile{File: file, keyMetadata: keyMetadata}, nil
+}
+
+// plaintextInputFile is an [EncryptedInputFile] that performs no decryption.
+type plaintextInputFile struct {
+	icebergio.File
+	keyMetadata EncryptionKeyMetadata
+}
+
+var _ EncryptedInputFile = (*plaintextInputFile)(nil)
+
+func (f *plaintextInputFile) KeyMetadata() EncryptionKeyMetadata { return f.keyMetadata }
+
+// plaintextOutputFile is an [EncryptedOutputFile] that performs no encryption.
+type plaintextOutputFile struct {
+	icebergio.FileWriter
+}
+
+var _ EncryptedOutputFile = (*plaintextOutputFile)(nil)
+
+func (f *plaintextOutputFile) KeyMetadata() EncryptionKeyMetadata { return nil }
diff --git a/encryption/encryption_test.go b/encryption/encryption_test.go
new file mode 100644
index 00000000..79381cfd
--- /dev/null
+++ b/encryption/encryption_test.go
@@ -0,0 +1,295 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package encryption_test
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"io/fs"
+	"testing"
+
+	"github.com/apache/iceberg-go/encryption"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sync/errgroup"
+)
+
+// ---------------------------------------------------------------------------
+// Minimal in-memory io.File / io.FileWriter stubs for testing
+// ---------------------------------------------------------------------------
+
+// memFile is a minimal in-memory implementation of icebergio.File.
+type memFile struct {
+	r *bytes.Reader
+}
+
+func newMemFile(data []byte) *memFile {
+	buf := make([]byte, len(data))
+	copy(buf, data)
+
+	return &memFile{r: bytes.NewReader(buf)}
+}
+
+func (f *memFile) Stat() (fs.FileInfo, error)              { return nil, nil }
+func (f *memFile) Read(p []byte) (int, error)              { return f.r.Read(p) }
+func (f *memFile) Seek(off int64, w int) (int64, error)    { return f.r.Seek(off, w) }
+func (f *memFile) Close() error                            { return nil }
+func (f *memFile) ReadAt(p []byte, off int64) (int, error) { return f.r.ReadAt(p, off) }
+
+// memFileWriter is a minimal in-memory implementation of icebergio.FileWriter.
+type memFileWriter struct{ buf bytes.Buffer }
+
+func (w *memFileWriter) Write(p []byte) (int, error)         { return w.buf.Write(p) }
+func (w *memFileWriter) Close() error                        { return nil }
+func (w *memFileWriter) ReadFrom(r io.Reader) (int64, error) { return io.Copy(&w.buf, r) }
+func (w *memFileWriter) Bytes() []byte                       { return w.buf.Bytes() }
+
+// ---------------------------------------------------------------------------
+// PlaintextEncryptionManager
+// ---------------------------------------------------------------------------
+
+func TestPlaintextEncryptionManager_OutputFile(t *testing.T) {
+	mgr := encryption.PlaintextEncryptionManager{}
+	fw := &memFileWriter{}
+
+	out, err := mgr.NewEncryptedOutputFile(t.Context(), fw, "")
+	require.NoError(t, err)
+
+	data := []byte("hello iceberg")
+	_, err = out.Write(data)
+	require.NoError(t, err)
+	require.NoError(t, out.Close())
+
+	assert.Nil(t, out.KeyMetadata(), "plaintext manager should return nil key metadata")
+	assert.Equal(t, data, fw.Bytes(), "plaintext manager must not alter data on write")
+}
+
+func TestPlaintextEncryptionManager_OutputFile_KeyIDRejected(t *testing.T) {
+	mgr := encryption.PlaintextEncryptionManager{}
+	fw := &memFileWriter{}
+
+	out, err := mgr.NewEncryptedOutputFile(t.Context(), fw, "some-key-id")
+	require.ErrorIs(t, err, encryption.ErrKeyIDNotSupported, "a non-empty keyID must fail closed, not silently write plaintext")
+	assert.Nil(t, out)
+}
+
+func TestPlaintextEncryptionManager_InputFile(t *testing.T) {
+	payload := []byte("plaintext data")
+	mgr := encryption.PlaintextEncryptionManager{}
+
+	in, err := mgr.NewDecryptedInputFile(t.Context(), newMemFile(payload), nil)
+	require.NoError(t, err)
+
+	assert.Nil(t, in.KeyMetadata())
+
+	got, err := io.ReadAll(in)
+	require.NoError(t, err)
+	assert.Equal(t, payload, got, "plaintext manager must not alter data on read")
+}
+
+func TestPlaintextEncryptionManager_InputFile_KeyMetadataRejected(t *testing.T) {
+	km := encryption.EncryptionKeyMetadata([]byte("some-metadata"))
+	mgr := encryption.PlaintextEncryptionManager{}
+
+	in, err := mgr.NewDecryptedInputFile(t.Context(), newMemFile([]byte("ciphertext")), km)
+	require.ErrorIs(t, err, encryption.ErrKeyMetadataNotSupported, "non-empty key metadata must fail closed, not silently expose bytes as plaintext")
+	assert.Nil(t, in)
+}
+
+func TestPlaintextEncryptionManager_InputFile_NilMetadata(t *testing.T) {
+	mgr := encryption.PlaintextEncryptionManager{}
+	in, err := mgr.NewDecryptedInputFile(t.Context(), newMemFile(nil), nil)
+	require.NoError(t, err)
+	assert.Nil(t, in.KeyMetadata())
+}
+
+// ---------------------------------------------------------------------------
+// InMemoryKeyManagementClient
+// ---------------------------------------------------------------------------
+
+func TestInMemoryKMS_WrapUnwrap(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	key := bytes.Repeat([]byte{0xAB}, 32) // AES-256 master key
+	require.NoError(t, kms.AddKey("master-1", key))
+
+	plaintext := []byte("my-dek-bytes-here-16") // 20-byte DEK
+	ctx := t.Context()
+
+	wrapped, err := kms.WrapKey(ctx, "master-1", plaintext)
+	require.NoError(t, err)
+	assert.NotEqual(t, plaintext, wrapped, "wrapped key must differ from plaintext")
+
+	unwrapped, err := kms.UnwrapKey(ctx, "master-1", wrapped)
+	require.NoError(t, err)
+	assert.Equal(t, plaintext, unwrapped)
+}
+
+func TestInMemoryKMS_WrapUnwrap_NonDeterministic(t *testing.T) {
+	// Each call to WrapKey must produce a different ciphertext (random nonce).
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x01}, 16)))
+	ctx := t.Context()
+
+	dek := []byte("same-dek-bytes!!")
+	w1, err := kms.WrapKey(ctx, "k", dek)
+	require.NoError(t, err)
+	w2, err := kms.WrapKey(ctx, "k", dek)
+	require.NoError(t, err)
+	assert.NotEqual(t, w1, w2, "each wrap must use a unique nonce")
+}
+
+func TestInMemoryKMS_AddKey_InvalidLength(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	err := kms.AddKey("bad", []byte("tooshort")) // 8 bytes — invalid
+	require.ErrorIs(t, err, encryption.ErrInvalidKeyLength)
+}
+
+func TestInMemoryKMS_UnknownKeyID(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	_, err := kms.WrapKey(t.Context(), "no-such-key", []byte("data"))
+	require.ErrorIs(t, err, encryption.ErrUnknownKeyID)
+}
+
+func TestInMemoryKMS_SupportsKeyGeneration(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	assert.True(t, kms.SupportsKeyGeneration())
+}
+
+func TestInMemoryKMS_GenerateKey(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("kek", bytes.Repeat([]byte{0xFF}, 32)))
+	ctx := t.Context()
+
+	plaintext, wrapped, err := kms.GenerateKey(ctx, "kek", 32)
+	require.NoError(t, err)
+	assert.Len(t, plaintext, 32)
+	assert.NotEmpty(t, wrapped)
+
+	// Round-trip: unwrap should give back the generated DEK.
+	recovered, err := kms.UnwrapKey(ctx, "kek", wrapped)
+	require.NoError(t, err)
+	assert.Equal(t, plaintext, recovered)
+}
+
+func TestInMemoryKMS_GenerateKey_InvalidLength(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x00}, 16)))
+	_, _, err := kms.GenerateKey(t.Context(), "k", 0)
+	require.ErrorIs(t, err, encryption.ErrInvalidKeyLength)
+}
+
+func TestInMemoryKMS_TamperDetection(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x42}, 32)))
+	ctx := t.Context()
+
+	wrapped, err := kms.WrapKey(ctx, "k", []byte("important-dek!!"))
+	require.NoError(t, err)
+
+	// Flip one byte in the ciphertext portion (after the 12-byte nonce).
+	tampered := make([]byte, len(wrapped))
+	copy(tampered, wrapped)
+	tampered[12] ^= 0xFF
+
+	_, err = kms.UnwrapKey(ctx, "k", tampered)
+	require.ErrorIs(t, err, encryption.ErrAuthenticationFailed, "tampered ciphertext must fail authentication")
+}
+
+func TestInMemoryKMS_ShortCiphertext(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x33}, 16)))
+
+	_, err := kms.UnwrapKey(t.Context(), "k", []byte{0x00, 0x01}) // shorter than AES-GCM nonce
+	require.ErrorIs(t, err, encryption.ErrCiphertextTooShort)
+}
+
+func TestInMemoryKMS_CrossKeyConfusion(t *testing.T) {
+	// Ciphertext produced with one KEK must not decrypt under another KEK,
+	// even if both KEKs are the same length.
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("a", bytes.Repeat([]byte{0x01}, 32)))
+	require.NoError(t, kms.AddKey("b", bytes.Repeat([]byte{0x02}, 32)))
+	ctx := t.Context()
+
+	wrapped, err := kms.WrapKey(ctx, "a", []byte("dek-under-key-a!"))
+	require.NoError(t, err)
+
+	_, err = kms.UnwrapKey(ctx, "b", wrapped)
+	require.ErrorIs(t, err, encryption.ErrAuthenticationFailed)
+}
+
+func TestInMemoryKMS_ConcurrentAccess(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x11}, 16)))
+	ctx := t.Context()
+	dek := []byte("concurrent-dek!!")
+
+	var g errgroup.Group
+	for range 20 {
+		g.Go(func() error {
+			wrapped, err := kms.WrapKey(ctx, "k", dek)
+			if err != nil {
+				return err
+			}
+			got, err := kms.UnwrapKey(ctx, "k", wrapped)
+			if err != nil {
+				return err
+			}
+			if !bytes.Equal(got, dek) {
+				return errors.New("round-trip mismatch")
+			}
+
+			return nil
+		})
+	}
+	require.NoError(t, g.Wait())
+}
+
+func TestInMemoryKMS_AddKey_IsolatesCopy(t *testing.T) {
+	kms := encryption.NewInMemoryKeyManagementClient()
+	masterKey := bytes.Repeat([]byte{0xAA}, 32)
+	require.NoError(t, kms.AddKey("k", masterKey))
+
+	// Mutate the original slice after registration.
+	masterKey[0] = 0x00
+
+	// Wrap/unwrap must still work with the original key bytes.
+	ctx := t.Context()
+	wrapped, err := kms.WrapKey(ctx, "k", []byte("data-dek-12345678"))
+	require.NoError(t, err)
+	got, err := kms.UnwrapKey(ctx, "k", wrapped)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("data-dek-12345678"), got)
+}
+
+func TestInMemoryKMS_AddKey_Overwrite(t *testing.T) {
+	// AddKey documents that re-registering a keyID replaces the KEK. A wrap
+	// under the old KEK must no longer decrypt after the replacement.
+	kms := encryption.NewInMemoryKeyManagementClient()
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x01}, 32)))
+	ctx := t.Context()
+
+	wrapped, err := kms.WrapKey(ctx, "k", []byte("before-rotation!"))
+	require.NoError(t, err)
+
+	require.NoError(t, kms.AddKey("k", bytes.Repeat([]byte{0x02}, 32)))
+
+	_, err = kms.UnwrapKey(ctx, "k", wrapped)
+	require.ErrorIs(t, err, encryption.ErrAuthenticationFailed)
+}
diff --git a/encryption/kms.go b/encryption/kms.go
new file mode 100644
index 00000000..5ccc4bcc
--- /dev/null
+++ b/encryption/kms.go
@@ -0,0 +1,225 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package encryption
+
+import (
+	"context"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"io"
+	"sync"
+)
+
+// Sentinel errors returned by [KeyManagementClient] implementations. Callers
+// should test with [errors.Is] rather than string matching.
+var (
+	// ErrUnknownKeyID is returned when a KMS client is asked to wrap or unwrap
+	// with a key ID it does not know about.
+	ErrUnknownKeyID = errors.New("encryption: unknown key ID")
+
+	// ErrInvalidKeyLength is returned when a key or requested key length is not
+	// valid for the underlying cipher (for example, a KEK that is not 16, 24,
+	// or 32 bytes for AES, or a DEK request of length <= 0).
+	ErrInvalidKeyLength = errors.New("encryption: invalid key length")
+
+	// ErrCiphertextTooShort is returned when a wrapped key or encrypted payload
+	// is smaller than the minimum required (e.g. the AES-GCM nonce prefix).
+	ErrCiphertextTooShort = errors.New("encryption: ciphertext too short")
+
+	// ErrAuthenticationFailed is returned when an authenticated decryption
+	// primitive rejects its input (tampering, wrong key, or corruption).
+	ErrAuthenticationFailed = errors.New("encryption: authentication failed")
+)
+
+// KeyManagementClient is the interface for a Key Management Service (KMS) that
+// wraps and unwraps data encryption keys (DEKs) using key encryption keys
+// (KEKs) managed externally by the KMS.
+//
+// In the standard envelope-encryption model:
+//   - A KEK is identified by a key ID (the table property encryption.key-id).
+//   - A fresh DEK is generated per-file (or per-rotation interval).
+//   - The DEK is wrapped by the KMS and stored in the file's key_metadata field.
+//   - On read, the wrapped DEK is unwrapped by the KMS to decrypt the file.
+//
+// Implementations are responsible for authentication, authorization, and
+// network communication with the KMS backend.
+type KeyManagementClient interface {
+	// WrapKey encrypts (wraps) plaintextKey using the KEK identified by keyID.
+	// The returned bytes are an opaque, KMS-specific wrapped key blob.
+	WrapKey(ctx context.Context, keyID string, plaintextKey []byte) ([]byte, error)
+
+	// UnwrapKey decrypts (unwraps) wrappedKey using the KEK identified by keyID.
+	// It returns the original plaintext DEK.
+	UnwrapKey(ctx context.Context, keyID string, wrappedKey []byte) ([]byte, error)
+
+	// SupportsKeyGeneration reports whether this client can generate new DEKs
+	// server-side. When false, callers should generate DEKs locally and use
+	// [WrapKey] to protect them.
+	SupportsKeyGeneration() bool
+
+	// GenerateKey generates a new DEK of the given byte length, returning both
+	// the plaintext DEK and its KMS-wrapped form. This is only valid when
+	// [SupportsKeyGeneration] returns true.
+	GenerateKey(ctx context.Context, keyID string, length int) (plaintext, wrapped []byte, err error)
+}
+
+// InMemoryKeyManagementClient is a [KeyManagementClient] backed by an
+// in-memory map of master (key-encryption) keys. Key wrapping and unwrapping
+// use AES-GCM.
+//
+// # Warning
+//
+// InMemoryKeyManagementClient is intended for testing only. All keys are held
+// in plaintext in process memory with no persistence, access control, or audit
+// logging. Do not use it in production.
+type InMemoryKeyManagementClient struct {
+	mu   sync.RWMutex
+	keys map[string][]byte // keyID -> raw KEK bytes
+}
+
+var _ KeyManagementClient = (*InMemoryKeyManagementClient)(nil)
+
+// NewInMemoryKeyManagementClient creates a new [InMemoryKeyManagementClient]
+// with no pre-loaded keys. Register KEKs with [AddKey] before use.
+func NewInMemoryKeyManagementClient() *InMemoryKeyManagementClient {
+	return &InMemoryKeyManagementClient{keys: make(map[string][]byte)}
+}
+
+// AddKey registers a master key (KEK) under keyID. masterKey must be 16, 24,
+// or 32 bytes for AES-128, AES-192, or AES-256 respectively. If keyID is
+// already registered, its KEK is silently replaced.
+func (c *InMemoryKeyManagementClient) AddKey(keyID string, masterKey []byte) error {
+	switch len(masterKey) {
+	case 16, 24, 32: // valid AES-GCM key lengths
+	default:
+		return fmt.Errorf("%w: master key for %q must be 16, 24, or 32 bytes; got %d", ErrInvalidKeyLength, keyID, len(masterKey))
+	}
+	keyCopy := make([]byte, len(masterKey))
+	copy(keyCopy, masterKey)
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.keys[keyID] = keyCopy
+
+	return nil
+}
+
+// WrapKey encrypts plaintextKey with the KEK identified by keyID using
+// AES-GCM. The returned ciphertext layout is:
+//
+//	12-byte random nonce || AES-GCM ciphertext || 16-byte GCM authentication tag
+func (c *InMemoryKeyManagementClient) WrapKey(_ context.Context, keyID string, plaintextKey []byte) ([]byte, error) {
+	kek, err := c.getKey(keyID)
+	if err != nil {
+		return nil, err
+	}
+
+	return aesgcmSeal(kek, plaintextKey)
+}
+
+// UnwrapKey decrypts wrappedKey using the KEK identified by keyID. The
+// wrappedKey must have been produced by [WrapKey] or [GenerateKey].
+func (c *InMemoryKeyManagementClient) UnwrapKey(_ context.Context, keyID string, wrappedKey []byte) ([]byte, error) {
+	kek, err := c.getKey(keyID)
+	if err != nil {
+		return nil, err
+	}
+
+	return aesgcmOpen(kek, wrappedKey)
+}
+
+// SupportsKeyGeneration returns true; the in-memory client generates DEKs
+// locally using crypto/rand.
+func (c *InMemoryKeyManagementClient) SupportsKeyGeneration() bool { return true }
+
+// GenerateKey generates a cryptographically random DEK of the given byte
+// length, wraps it with the KEK identified by keyID, and returns both the
+// plaintext DEK and the wrapped form.
+func (c *InMemoryKeyManagementClient) GenerateKey(ctx context.Context, keyID string, length int) (plaintext, wrapped []byte, err error) {
+	if length <= 0 {
+		return nil, nil, fmt.Errorf("%w: key length must be positive, got %d", ErrInvalidKeyLength, length)
+	}
+	plaintext = make([]byte, length)
+	if _, err = io.ReadFull(rand.Reader, plaintext); err != nil {
+		return nil, nil, fmt.Errorf("encryption: failed to generate random key: %w", err)
+	}
+	wrapped, err = c.WrapKey(ctx, keyID, plaintext)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return plaintext, wrapped, nil
+}
+
+// getKey returns the KEK for keyID, or an error wrapping [ErrUnknownKeyID] if
+// not found. The returned slice is the live map entry and must not be mutated
+// by callers; it is safe to read concurrently because [AddKey] copies its
+// input on ingress and never mutates a previously stored KEK in place.
+func (c *InMemoryKeyManagementClient) getKey(keyID string) ([]byte, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	kek, ok := c.keys[keyID]
+	if !ok {
+		return nil, fmt.Errorf("%w: %q", ErrUnknownKeyID, keyID)
+	}
+
+	return kek, nil
+}
+
+// aesgcmSeal encrypts plaintext with key using AES-GCM with a random 12-byte
+// nonce. The nonce is prepended to the returned ciphertext.
+func aesgcmSeal(key, plaintext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("encryption: failed to create AES cipher: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("encryption: failed to create GCM: %w", err)
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err = io.ReadFull(rand.Reader, nonce); err != nil {
+		return nil, fmt.Errorf("encryption: failed to generate nonce: %w", err)
+	}
+	// Seal appends ciphertext+tag to nonce, producing: nonce || ciphertext || tag.
+	return gcm.Seal(nonce, nonce, plaintext, nil), nil
+}
+
+// aesgcmOpen decrypts AES-GCM ciphertext produced by [aesgcmSeal].
+func aesgcmOpen(key, ciphertext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("encryption: failed to create AES cipher: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("encryption: failed to create GCM: %w", err)
+	}
+	nonceSize := gcm.NonceSize()
+	if len(ciphertext) < nonceSize {
+		return nil, fmt.Errorf("%w: need at least %d bytes for AES-GCM nonce, got %d", ErrCiphertextTooShort, nonceSize, len(ciphertext))
+	}
+	plaintext, err := gcm.Open(nil, ciphertext[:nonceSize], ciphertext[nonceSize:], nil)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrAuthenticationFailed, err)
+	}
+
+	return plaintext, nil
+}