crypto and kms

Two tightly-coupled packages that own everything to do with encryption-at-rest.

internal/crypto

File	What it does
crypto.go	EncryptedObject, DecryptedObject. Glues KMS + per-object DEK + the sio cipher.
auto-encryption.go	Server-default SSE: forces SSE-S3 when configured.
header.go	SSE request/response headers (X-Amz-Server-Side-Encryption*).
key.go	Object encryption keys, KDF helpers.
metadata.go	Per-object SSE metadata stored in xl.meta.
sse.go	Generic SSE entry points and dispatcher.
sse-s3.go, sse-kms.go, sse-c.go	The three SSE variants.

Encryption is built on github.com/minio/sio, which provides AES-256-GCM and ChaCha20-Poly1305 over fixed-size segments. Each part of a multipart upload uses its own derived key.

The package is consumed almost exclusively by cmd/encryption-v1.go and the related read/write paths in cmd/object-handlers.go and cmd/object-multipart-handlers.go.

internal/kms

File	What it does
kms.go	The KMS interface every backend implements.
single-key.go	Local KEK derived from MINIO_KMS_SECRET_KEY.
kes.go, kes-conn.go	KES client (mTLS to the MinIO KES service).
builtin.go	Built-in cipher used internally by single-key.go.
policy.go	Encryption policy decisions (which scheme applies).
stub.go	No-op KMS for tests.
config.go	Config glue.

The interface is small: GenerateKey, DecryptKey, Status, CreateKey, ListKeys. Backends implement those and plug in via internal/kms/config.go.

How they interact

graph LR
    PUT[ObjectLayer.PutObject] --> CR[crypto.EncryptedObject]
    CR --> KMS[kms.KMS]
    KMS --> KES[KES server]
    CR --> SIO[sio cipher]
    SIO --> EC[Erasure encoder]

• crypto calls kms.GenerateKey to obtain a wrapped DEK.
• crypto initialises the sio cipher with the unwrapped DEK.
• crypto writes the wrapped DEK + SSE metadata into the object's xl.meta so a future GET can reconstruct.

Integration points

• Wired into the runtime by cmd/encryption-v1.go (handler glue) and cmd/server-main.go (KMS bootstrap).
• KMS configuration lives in internal/config/ (no dedicated subdirectory; the env vars are read directly).
• internal/bucket/encryption/ parses the bucket-level PutBucketEncryption XML.

Entry points for modification

• New SSE variant. Add a file in internal/crypto/, update header.go and sse.go to detect it.
• New KMS backend. Implement kms.KMS in a new file under internal/kms/, register via internal/kms/config.go.
• Auto-encryption policy. internal/crypto/auto-encryption.go is the single decision point.

See KMS and encryption for the runtime view.