cmek split 4/8: encryption metadata cache and manager

go.mod

@@ -1,8 +1,9 @@
 module github.com/pingcap/ticdc
 
-go 1.25.8
+go 1.25.5
 
 require (
+	cloud.google.com/go/kms v1.15.8
 	cloud.google.com/go/storage v1.39.1
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.20.0
 	github.com/BurntSushi/toml v1.5.0
@@ -12,10 +13,11 @@ require (
 	github.com/agiledragon/gomonkey/v2 v2.11.0
 	github.com/apache/pulsar-client-go v0.13.0
 	github.com/aws/aws-sdk-go v1.55.5
-	github.com/aws/aws-sdk-go-v2 v1.40.0
+	github.com/aws/aws-sdk-go-v2 v1.41.1
 	github.com/aws/aws-sdk-go-v2/config v1.32.2
 	github.com/aws/aws-sdk-go-v2/credentials v1.19.2
 	github.com/aws/aws-sdk-go-v2/service/glue v1.134.1
+	github.com/aws/aws-sdk-go-v2/service/kms v1.49.5
 	github.com/benbjohnson/clock v1.3.5
 	github.com/bradleyjkemp/grpc-tools v0.2.5
 	github.com/cenkalti/backoff/v4 v4.2.1
@@ -91,6 +93,7 @@ require (
 	golang.org/x/term v0.34.0
 	golang.org/x/text v0.29.0
 	golang.org/x/time v0.12.0
+	google.golang.org/api v0.170.0
 	google.golang.org/grpc v1.67.1
 	google.golang.org/protobuf v1.36.6
 )
@@ -109,8 +112,7 @@ require (
 	cloud.google.com/go v0.112.2 // indirect
 	cloud.google.com/go/compute/metadata v0.5.0 // indirect
 	cloud.google.com/go/iam v1.1.7 // indirect
-	cloud.google.com/go/kms v1.15.8 // indirect
-	filippo.io/edwards25519 v1.1.1 // indirect
+	filippo.io/edwards25519 v1.1.0 // indirect
 	github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 // indirect
 	github.com/99designs/keyring v1.2.1 // indirect
 	github.com/AthenZ/athenz v1.10.39 // indirect
@@ -142,8 +144,8 @@ require (
 	github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.3 // indirect
 	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.14 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.14 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.14 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.14 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.3 // indirect
@@ -155,7 +157,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sso v1.30.5 // indirect
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.10 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.2 // indirect
-	github.com/aws/smithy-go v1.23.2 // indirect
+	github.com/aws/smithy-go v1.24.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bits-and-blooms/bitset v1.14.3 // indirect
 	github.com/blacktear23/go-proxyprotocol v1.0.6 // indirect
@@ -363,7 +365,6 @@ require (
 	golang.org/x/mod v0.27.0 // indirect
 	golang.org/x/tools v0.36.0 // indirect
 	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect
-	google.golang.org/api v0.170.0 // indirect
 	google.golang.org/genproto v0.0.0-20240401170217-c3f982113cda // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20240814211410-ddb44dafa142 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250425173222-7b384671a197 // indirect

go.sum

@@ -1243,8 +1243,8 @@ cloud.google.com/go/workflows v1.12.2/go.mod h1:+OmBIgNqYJPVggnMo9nqmizW0qEXHhmn
 cloud.google.com/go/workflows v1.12.3/go.mod h1:fmOUeeqEwPzIU81foMjTRQIdwQHADi/vEr1cx9R1m5g=
 cloud.google.com/go/workflows v1.12.4/go.mod h1:yQ7HUqOkdJK4duVtMeBCAOPiN1ZF1E9pAMX51vpwB/w=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
-filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
-filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 gioui.org v0.0.0-20210308172011-57750fc8a0a6/go.mod h1:RSH6KIUZ0p2xy5zHDxgAM4zumjgTw83q2ge/PI+yyw8=
 git.sr.ht/~sbinet/gg v0.3.1/go.mod h1:KGYtlADtqsqANL9ueOFkWymvzUvLMQllU5Ixo+8v3pc=
 github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 h1:/vQbFIOMbk2FiG/kXiLl8BRyzTWDw7gX/Hz7Dd5eDMs=
@@ -1392,8 +1392,8 @@ github.com/aws/aws-sdk-go v1.32.6/go.mod h1:5zCpMtNQVjRREroY7sYe8lOMRSxkhG6MZveU
 github.com/aws/aws-sdk-go v1.44.204/go.mod h1:aVsgQcEevwlmQ7qHE9I3h+dtQgpqhFB+i8Phjh7fkwI=
 github.com/aws/aws-sdk-go v1.55.5 h1:KKUZBfBoyqy5d3swXyiC7Q76ic40rYcbqH7qjh59kzU=
 github.com/aws/aws-sdk-go v1.55.5/go.mod h1:eRwEWoyTWFMVYVQzKMNHWP5/RV4xIUGMQfXQHfHkpNU=
-github.com/aws/aws-sdk-go-v2 v1.40.0 h1:/WMUA0kjhZExjOQN2z3oLALDREea1A7TobfuiBrKlwc=
-github.com/aws/aws-sdk-go-v2 v1.40.0/go.mod h1:c9pm7VwuW0UPxAEYGyTmyurVcNrbF6Rt/wixFqDhcjE=
+github.com/aws/aws-sdk-go-v2 v1.41.1 h1:ABlyEARCDLN034NhxlRUSZr4l71mh+T5KAeGh6cerhU=
+github.com/aws/aws-sdk-go-v2 v1.41.1/go.mod h1:MayyLB8y+buD9hZqkCW3kX1AKq07Y5pXxtgB+rRFhz0=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.3 h1:DHctwEM8P8iTXFxC/QK0MRjwEpWQeM9yzidCRjldUz0=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.3/go.mod h1:xdCzcZEtnSTKVDOmUZs4l/j3pSV6rpo1WXl5ugNsL8Y=
 github.com/aws/aws-sdk-go-v2/config v1.32.2 h1:4liUsdEpUUPZs5WVapsJLx5NPmQhQdez7nYFcovrytk=
@@ -1402,10 +1402,10 @@ github.com/aws/aws-sdk-go-v2/credentials v1.19.2 h1:qZry8VUyTK4VIo5aEdUcBjPZHL2v
 github.com/aws/aws-sdk-go-v2/credentials v1.19.2/go.mod h1:YUqm5a1/kBnoK+/NY5WEiMocZihKSo15/tJdmdXnM5g=
 github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.14 h1:WZVR5DbDgxzA0BJeudId89Kmgy6DIU4ORpxwsVHz0qA=
 github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.14/go.mod h1:Dadl9QO0kHgbrH1GRqGiZdYtW5w+IXXaBNCHTIaheM4=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.14 h1:PZHqQACxYb8mYgms4RZbhZG0a7dPW06xOjmaH0EJC/I=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.14/go.mod h1:VymhrMJUWs69D8u0/lZ7jSB6WgaG/NqHi3gX0aYf6U0=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.14 h1:bOS19y6zlJwagBfHxs0ESzr1XCOU2KXJCWcq3E2vfjY=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.14/go.mod h1:1ipeGBMAxZ0xcTm6y6paC2C/J6f6OO7LBODV9afuAyM=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17 h1:xOLELNKGp2vsiteLsvLPwxC+mYmO6OZ8PYgiuPJzF8U=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17/go.mod h1:5M5CI3D12dNOtH3/mk6minaRwI2/37ifCURZISxA/IQ=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17 h1:WWLqlh79iO48yLkj1v3ISRNiv+3KdQoZ6JWyfcsyQik=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17/go.mod h1:EhG22vHRrvF8oXSTYStZhJc1aUgKtnJe+aOiFEV90cM=
 github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 h1:WKuaxf++XKWlHWu9ECbMlha8WOEGm0OUEZqm4K/Gcfk=
 github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4/go.mod h1:ZWy7j6v1vWGmPReu0iSGvRiise4YI5SkR3OHKTZ6Wuc=
 github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.14 h1:ITi7qiDSv/mSGDSWNpZ4k4Ve0DQR6Ug2SJQ8zEHoDXg=
@@ -1420,6 +1420,8 @@ github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.14 h1:FIouAnCE
 github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.14/go.mod h1:UTwDc5COa5+guonQU8qBikJo1ZJ4ln2r1MkF7Dqag1E=
 github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.14 h1:FzQE21lNtUor0Fb7QNgnEyiRCBlolLTX/Z1j65S7teM=
 github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.14/go.mod h1:s1ydyWG9pm3ZwmmYN21HKyG9WzAZhYVW85wMHs5FV6w=
+github.com/aws/aws-sdk-go-v2/service/kms v1.49.5 h1:DKibav4XF66XSeaXcrn9GlWGHos6D/vJ4r7jsK7z5CE=
+github.com/aws/aws-sdk-go-v2/service/kms v1.49.5/go.mod h1:1SdcmEGUEQE1mrU2sIgeHtcMSxHuybhPvuEPANzIDfI=
 github.com/aws/aws-sdk-go-v2/service/s3 v1.92.1 h1:OgQy/+0+Kc3khtqiEOk23xQAglXi3Tj0y5doOxbi5tg=
 github.com/aws/aws-sdk-go-v2/service/s3 v1.92.1/go.mod h1:wYNqY3L02Z3IgRYxOBPH9I1zD9Cjh9hI5QOy/eOjQvw=
 github.com/aws/aws-sdk-go-v2/service/signin v1.0.2 h1:MxMBdKTYBjPQChlJhi4qlEueqB1p1KcbTEa7tD5aqPs=
@@ -1430,8 +1432,8 @@ github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.10 h1:GtsxyiF3Nd3JahRBJbxLCCd
 github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.10/go.mod h1:/j67Z5XBVDx8nZVp9EuFM9/BS5dvBznbqILGuu73hug=
 github.com/aws/aws-sdk-go-v2/service/sts v1.41.2 h1:a5UTtD4mHBU3t0o6aHQZFJTNKVfxFWfPX7J0Lr7G+uY=
 github.com/aws/aws-sdk-go-v2/service/sts v1.41.2/go.mod h1:6TxbXoDSgBQ225Qd8Q+MbxUxUh6TtNKwbRt/EPS9xso=
-github.com/aws/smithy-go v1.23.2 h1:Crv0eatJUQhaManss33hS5r40CG3ZFH+21XSkqMrIUM=
-github.com/aws/smithy-go v1.23.2/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
+github.com/aws/smithy-go v1.24.0 h1:LpilSUItNPFr1eY85RYgTIg5eIEPtvFbskaFcmmIUnk=
+github.com/aws/smithy-go v1.24.0/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
 github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA=
 github.com/benbjohnson/clock v1.3.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA=
 github.com/benbjohnson/clock v1.3.5 h1:VvXlSJBzZpA/zum6Sj74hxwYI2DIxRWuNIoXAzHZz5o=

pkg/config/debug.go

@@ -36,6 +36,9 @@ type DebugConfig struct {
 	SchemaStore *SchemaStoreConfig `toml:"schema-store" json:"schema_store"`
 
 	EventService *EventServiceConfig `toml:"event-service" json:"event_service"`
+
+	// Encryption is the configuration for CMEK encryption at rest
+	Encryption *EncryptionConfig `toml:"encryption" json:"encryption"`
 }
 
 // ValidateAndAdjust validates and adjusts the debug configuration
@@ -140,3 +143,67 @@ func NewDefaultEventServiceConfig() *EventServiceConfig {
 		EnableRemoteEventService: true,
 	}
 }
+
+// EncryptionConfig represents config for CMEK encryption at rest
+type EncryptionConfig struct {
+	// EnableEncryption enables encryption for data at rest
+	EnableEncryption bool `toml:"enable-encryption" json:"enable_encryption"`
+
+	// MetaRefreshInterval is the interval for refreshing encryption metadata (default: 1 hour)
+	MetaRefreshInterval TomlDuration `toml:"meta-refresh-interval" json:"meta_refresh_interval"`
+
+	// MetaCacheTTL is the TTL for caching encryption metadata (default: 1 hour)
+	MetaCacheTTL TomlDuration `toml:"meta-cache-ttl" json:"meta_cache_ttl"`
+
+	// AllowDegradeOnError allows graceful degradation to unencrypted mode on encryption errors
+	AllowDegradeOnError bool `toml:"allow-degrade-on-error" json:"allow_degrade_on_error"`
+
+	// KMS contains optional KMS client overrides. If unset, TiCDC will use the
+	// default credential chain of the corresponding cloud provider.
+	KMS *KMSConfig `toml:"kms" json:"kms"`
+}
+
+// KMSConfig contains KMS configuration for different cloud providers.
+type KMSConfig struct {
+	AWS *AWSKMSConfig `toml:"aws" json:"aws"`
+	GCP *GCPKMSConfig `toml:"gcp" json:"gcp"`
+}
+
+type AWSKMSConfig struct {
+	// Region overrides the region from TiKV encryption metadata.
+	Region string `toml:"region" json:"region"`
+	// Endpoint overrides the endpoint from TiKV encryption metadata.
+	Endpoint string `toml:"endpoint" json:"endpoint"`
+
+	// Profile configures the AWS shared config profile to use.
+	Profile string `toml:"profile" json:"profile"`
+
+	// Static credentials. If AccessKey is set, SecretAccessKey must also be set.
+	AccessKey       string `toml:"access-key" json:"access_key"`
+	SecretAccessKey string `toml:"secret-access-key" json:"secret_access_key"`
+	SessionToken    string `toml:"session-token" json:"session_token"`
+}
+
+type GCPKMSConfig struct {
+	// Endpoint overrides the endpoint from TiKV encryption metadata.
+	Endpoint string `toml:"endpoint" json:"endpoint"`
+
+	// CredentialsFile specifies a service account JSON file path.
+	CredentialsFile string `toml:"credentials-file" json:"credentials_file"`
+	// CredentialsJSON specifies a service account JSON content.
+	CredentialsJSON string `toml:"credentials-json" json:"credentials_json"`
+}
+
+// NewDefaultEncryptionConfig returns the default encryption configuration
+func NewDefaultEncryptionConfig() *EncryptionConfig {
+	return &EncryptionConfig{
+		EnableEncryption:    false,
+		MetaRefreshInterval: TomlDuration(1 * time.Hour),
+		MetaCacheTTL:        TomlDuration(1 * time.Hour),
+		AllowDegradeOnError: true,
+		KMS: &KMSConfig{
+			AWS: &AWSKMSConfig{},
+			GCP: &GCPKMSConfig{},
+		},
+	}
+}

pkg/config/server.go

@@ -126,6 +126,7 @@ var defaultServerConfig = &ServerConfig{
 		EventStore:   NewDefaultEventStoreConfig(),
 		SchemaStore:  NewDefaultSchemaStoreConfig(),
 		EventService: NewDefaultEventServiceConfig(),
+		Encryption:   NewDefaultEncryptionConfig(),
 	},
 	ClusterID:              "default",
 	GcTunerMemoryThreshold: DisableMemoryLimit,

pkg/encryption/cipher.go

@@ -0,0 +1,107 @@
+// Copyright 2025 PingCAP, Inc.
+//
+// Licensed 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package encryption
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+
+	cerrors "github.com/pingcap/ticdc/pkg/errors"
+)
+
+// Cipher is the interface for encryption/decryption operations
+type Cipher interface {
+	// Encrypt encrypts data using the provided key and IV
+	Encrypt(data, key, iv []byte) ([]byte, error)
+
+	// Decrypt decrypts data using the provided key and IV
+	Decrypt(data, key, iv []byte) ([]byte, error)
+
+	// IVSize returns the required IV size in bytes
+	IVSize() int
+}
+
+// AES256CTRCipher implements AES-CTR encryption for AES key sizes.
+type AES256CTRCipher struct{}
+
+// NewAES256CTRCipher creates a new AES-CTR cipher.
+func NewAES256CTRCipher() *AES256CTRCipher {
+	return &AES256CTRCipher{}
+}
+
+// IVSize returns the IV size for AES-CTR (16 bytes)
+func (c *AES256CTRCipher) IVSize() int {
+	return aes.BlockSize
+}
+
+func isValidAESKeySize(key []byte) bool {
+	switch len(key) {
+	case 16, 24, 32:
+		return true
+	default:
+		return false
+	}
+}
+
+// Encrypt encrypts data using AES-CTR.
+func (c *AES256CTRCipher) Encrypt(data, key, iv []byte) ([]byte, error) {
+	if !isValidAESKeySize(key) {
+		return nil, cerrors.ErrEncryptionFailed.GenWithStackByArgs("key must be 16, 24, or 32 bytes for AES-CTR")
+	}
+	if len(iv) != c.IVSize() {
+		return nil, cerrors.ErrEncryptionFailed.GenWithStackByArgs("IV must be 16 bytes")
+	}
+
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, cerrors.ErrEncryptionFailed.Wrap(err)
+	}
+
+	stream := cipher.NewCTR(block, iv)
+	ciphertext := make([]byte, len(data))
+	stream.XORKeyStream(ciphertext, data)
+
+	return ciphertext, nil
+}
+
+// Decrypt decrypts data using AES-CTR.
+func (c *AES256CTRCipher) Decrypt(data, key, iv []byte) ([]byte, error) {
+	if !isValidAESKeySize(key) {
+		return nil, cerrors.ErrDecryptionFailed.GenWithStackByArgs("key must be 16, 24, or 32 bytes for AES-CTR")
+	}
+	if len(iv) != c.IVSize() {
+		return nil, cerrors.ErrDecryptionFailed.GenWithStackByArgs("IV must be 16 bytes")
+	}
+
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, cerrors.ErrDecryptionFailed.Wrap(err)
+	}
+
+	stream := cipher.NewCTR(block, iv)
+	plaintext := make([]byte, len(data))
+	stream.XORKeyStream(plaintext, data)
+
+	return plaintext, nil
+}
+
+// GenerateIV generates a random IV of the specified size
+func GenerateIV(size int) ([]byte, error) {
+	iv := make([]byte, size)
+	if _, err := rand.Read(iv); err != nil {
+		return nil, cerrors.ErrEncryptionFailed.Wrap(err)
+	}
+	return iv, nil
+}

pkg/encryption/cipher_test.go

@@ -0,0 +1,35 @@
+// Copyright 2025 PingCAP, Inc.
+//
+// Licensed 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package encryption
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestAES256CTREncryptDecrypt(t *testing.T) {
+	key := []byte("0123456789abcdef0123456789abcdef") // 32 bytes
+	iv := []byte("1234567890abcdef")                  // 16 bytes
+	plain := []byte("hello world")
+
+	cipherImpl := NewAES256CTRCipher()
+	encrypted, err := cipherImpl.Encrypt(plain, key, iv)
+	require.NoError(t, err)
+	require.NotEqual(t, plain, encrypted)
+
+	decrypted, err := cipherImpl.Decrypt(encrypted, key, iv)
+	require.NoError(t, err)
+	require.Equal(t, plain, decrypted)
+}

pkg/encryption/data_key_id.go

@@ -0,0 +1,34 @@
+// Copyright 2026 PingCAP, Inc.
+//
+// Licensed 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package encryption
+
+import "github.com/pingcap/errors"
+
+// DataKeyID represents a 3-byte data key identifier in the encryption header.
+type DataKeyID [3]byte
+
+// ToString converts DataKeyID to string.
+func (id DataKeyID) ToString() string {
+	return string(id[:])
+}
+
+// DataKeyIDFromString creates DataKeyID from string (must be 3 bytes).
+func DataKeyIDFromString(s string) (DataKeyID, error) {
+	if len(s) != 3 {
+		return DataKeyID{}, errors.New("data key ID must be exactly 3 bytes")
+	}
+	var id DataKeyID
+	copy(id[:], s)
+	return id, nil
+}