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
+}