Encryption

Relevant source files

• cmd/api-errors.go
• cmd/api-response.go
• cmd/api-router.go
• cmd/apierrorcode_string.go
• cmd/bucket-handlers.go
• cmd/bucket-replication.go
• cmd/encryption-v1.go
• cmd/encryption-v1_test.go
• cmd/generic-handlers.go
• cmd/generic-handlers_test.go
• cmd/handler-utils.go
• cmd/object-api-datatypes.go
• cmd/object-api-errors.go
• cmd/object-api-options.go
• cmd/object-api-utils.go
• cmd/object-api-utils_test.go
• cmd/object-handlers.go
• cmd/routers.go

This document describes MinIO's server-side encryption (SSE) implementation, covering encryption types, key management, object encryption/decryption workflows, and integration with Key Management Systems (KMS). For information about the IAM system that controls access to encrypted objects, see Identity and Access Management.

Overview

MinIO supports three server-side encryption modes compatible with the AWS S3 encryption API:

• SSE-C: Server-Side Encryption with Customer-provided keys
• SSE-S3: Server-Side Encryption with S3-managed keys (using KMS)
• SSE-KMS: Server-Side Encryption with KMS-managed keys and explicit key IDs

Encryption is transparent to clients after the initial request. Objects are encrypted at rest using AES-256-GCM, and encryption keys are sealed using either customer-provided keys (SSE-C) or keys managed by an external KMS (SSE-S3/SSE-KMS).

Sources: cmd/encryption-v1.go49-61 cmd/api-errors.go222-242

Encryption Types and Headers

SSE-C (Customer-Provided Keys)

SSE-C requires clients to provide encryption keys with each request. The key is transmitted via HTTP headers and never stored on the server.

Request Headers:

• X-Amz-Server-Side-Encryption-Customer-Algorithm: Must be AES256
• X-Amz-Server-Side-Encryption-Customer-Key: Base64-encoded 32-byte key
• X-Amz-Server-Side-Encryption-Customer-Key-MD5: MD5 of the key for validation

Response Headers:

• X-Amz-Server-Side-Encryption-Customer-Algorithm: Echoed back as AES256
• X-Amz-Server-Side-Encryption-Customer-Key-MD5: Echoed back for verification

SSE-C requests are rejected unless made over TLS to protect key material in transit.

Sources: cmd/generic-handlers.go450-469 cmd/object-handlers.go516-519

SSE-S3 (S3-Managed Encryption)

SSE-S3 uses a KMS to generate and manage encryption keys automatically. Clients request encryption by setting a single header.

Request Headers:

• X-Amz-Server-Side-Encryption: Must be AES256

Response Headers:

• X-Amz-Server-Side-Encryption: Set to AES256

The server automatically generates a unique data encryption key (DEK) for each object and seals it using the KMS.

Sources: cmd/object-handlers.go281-282 cmd/object-handlers.go508-509

SSE-KMS (KMS with Explicit Key ID)

SSE-KMS is similar to SSE-S3 but allows clients to specify a particular KMS key ID and optional encryption context.

Request Headers:

• X-Amz-Server-Side-Encryption: Must be aws:kms
• X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id: ARN or ID of the KMS key
• X-Amz-Server-Side-Encryption-Context: Optional base64-encoded JSON context

Response Headers:

• X-Amz-Server-Side-Encryption: Set to aws:kms
• X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id: KMS key ARN
• X-Amz-Server-Side-Encryption-Context: Encryption context if provided

Sources: cmd/object-handlers.go283-288 cmd/object-handlers.go510-515

Encryption Constants and Package Layout

Sources: cmd/encryption-v1.go63-76 cmd/encryption-v1.go89-101

Request Processing and Key Derivation

SSE-C Key Unsealing Flow

For SSE-C, the client-provided key is never stored. Instead, MinIO derives a unique object encryption key (OEK) using HMAC with the bucket and object name as context. This derived key is sealed and stored in the object metadata.

Sources: cmd/encryption-v1.go566-601 cmd/object-api-options.go64-72

SSE-S3/SSE-KMS Key Generation Flow

For SSE-S3 and SSE-KMS, MinIO generates a random data encryption key (DEK), seals it using the KMS, and stores the sealed key in the object's metadata. The DEK encrypts the actual object data.

Sources: cmd/encryption-v1.go436-481 cmd/encryption-v1.go522-563

Object Encryption Process

Single-Part Object Encryption

During a PUT operation, MinIO:

1. Validates encryption headers
2. Derives or generates the encryption key
3. Wraps the request body reader with sio.EncryptReader using the derived key
4. Stores encryption metadata (sealed key, IV, algorithm) in object user-defined metadata
5. Writes the encrypted data to storage

The encryption is done in a streaming fashion using the sio library, which implements the DARE (Data At Rest Encryption) format with 64 KiB packages.

Sources: cmd/encryption-v1.go522-563 cmd/encryption-v1.go602-652

Multipart Upload Encryption

For multipart uploads, each part is encrypted independently using the same object encryption key (OEK). The OEK is derived or generated during InitiateMultipartUpload and stored in the upload metadata.

Workflow:

1. NewMultipartUpload(): Generate/derive OEK, seal it, store in upload metadata
2. PutObjectPart(): Encrypt each part with the same OEK
3. CompleteMultipartUpload(): Combine encrypted parts, preserve metadata

Sources: cmd/encryption-v1.go719-783 cmd/encryption-v1.go827-873

Object Decryption Process

GET Request Decryption Flow

During a GET operation:

1. The object metadata is fetched
2. For SSE-C, the client-provided key is validated against the stored metadata
3. For SSE-S3/SSE-KMS, the sealed key is unsealed using the KMS
4. The data stream is wrapped with a decryption reader
5. The ETag is formatted to hide encryption details
6. Appropriate SSE headers are set in the response

Sources: cmd/object-handlers.go313-578 cmd/encryption-v1.go216-257

ETag Handling for Encrypted Objects

Encrypted objects have special ETag handling:

• SSE-S3 single-part objects: ETag is the encrypted MD5 hash, decrypted before returning to client
• SSE-C objects: ETag is formatted to appear as a regular MD5 but is actually derived from encrypted content
• Multipart objects: ETag includes part count suffix (e.g., {hash}-{partCount})

The DecryptETags() function processes batches of objects efficiently using bulk KMS decryption when available.

Sources: cmd/encryption-v1.go103-208 cmd/object-handlers.go520-521

Key Management and KMS Integration

KMS Interface

MinIO integrates with external Key Management Systems through the kms.KMS interface. The KMS is used to:

• Generate data encryption keys (DEKs)
• Seal (encrypt) DEKs for storage
• Unseal (decrypt) DEKs for object access

Sources: cmd/encryption-v1.go436-481 cmd/encryption-v1.go85-101

Bulk Decryption Optimization

For operations that need to decrypt multiple objects (e.g., ListObjects with metadata), MinIO uses bulk decryption APIs:

This reduces the number of KMS calls and improves performance for listing operations.

Sources: cmd/encryption-v1.go113-178

Replication with Encryption

SSE-C Replication

SSE-C encrypted objects cannot be directly replicated because the customer key is never stored. Instead, MinIO uses special internal headers to replicate the sealed encryption metadata:

Internal to Replication Header Mapping:

• X-Minio-Internal-Server-Side-Encryption-Sealed-Key → X-Minio-Replication-Server-Side-Encryption-Sealed-Key
• X-Minio-Internal-Server-Side-Encryption-Seal-Algorithm → X-Minio-Replication-Server-Side-Encryption-Seal-Algorithm
• X-Minio-Internal-Server-Side-Encryption-Iv → X-Minio-Replication-Server-Side-Encryption-Iv
• X-Minio-Internal-Encrypted-Multipart → X-Minio-Replication-Encrypted-Multipart
• X-Minio-Internal-Actual-Object-Size → X-Minio-Replication-Actual-Object-Size

For SSE-C objects, the encrypted checksum is transmitted via:

• X-Minio-Replication-Ssec-Crc: Encrypted CRC of the object

Sources: cmd/handler-utils.go96-114 cmd/bucket-replication.go800-814

SSE-S3/SSE-KMS Replication

For SSE-S3 and SSE-KMS objects, the sealed key metadata is replicated along with the encrypted object data. The target cluster must have access to the same KMS or a compatible key to unseal the keys.

Sources: cmd/bucket-replication.go778-873

Error Handling

Common Encryption Errors

Error Code	Description	HTTP Status
ErrInsecureSSECustomerRequest	SSE-C request over non-TLS connection	400 Bad Request
ErrInvalidSSECustomerAlgorithm	Invalid algorithm (must be AES256)	400 Bad Request
ErrInvalidSSECustomerKey	Invalid customer key format	400 Bad Request
ErrMissingSSECustomerKey	SSE-C key not provided	400 Bad Request
ErrMissingSSECustomerKeyMD5	SSE-C key MD5 not provided	400 Bad Request
ErrSSECustomerKeyMD5Mismatch	Key MD5 doesn't match	400 Bad Request
ErrInvalidEncryptionMethod	Invalid encryption method	400 Bad Request
ErrKMSNotConfigured	KMS not configured for SSE-S3/SSE-KMS	500 Internal Error
ErrKMSKeyNotFoundException	Specified KMS key not found	400 Bad Request
ErrIncompatibleEncryptionMethod	Conflicting encryption headers	400 Bad Request

Sources: cmd/api-errors.go227-242 cmd/encryption-v1.go49-61

TLS Requirement Enforcement

SSE-C requests are explicitly rejected if not made over TLS:

if !globalIsTLS && (crypto.SSEC.IsRequested(r.Header) || crypto.SSECopy.IsRequested(r.Header)) {
    writeErrorResponse(ctx, w, errorCodes.ToAPIErr(ErrInsecureSSECustomerRequest), r.URL)
    return
}

This validation occurs in the request validity middleware before any handler is invoked.

Sources: cmd/generic-handlers.go450-469

Implementation Details

DARE Format

MinIO uses the Data At Rest Encryption (DARE) format implemented by the sio library:

• Package size: 64 KiB of plaintext per package
• Package overhead: 32 bytes of metadata (authentication tag, nonce)
• Encryption: AES-256-GCM with random nonces
• Authentication: Each package is authenticated with AEAD

This format enables:

• Streaming encryption/decryption without loading entire objects into memory
• Random access to encrypted data (range requests)
• Data integrity verification

Sources: cmd/encryption-v1.go71-76 cmd/encryption-v1.go602-652

Metadata Storage

Encryption metadata is stored in the object's UserDefined map with reserved keys:

Sources: cmd/encryption-v1.go436-481 cmd/object-api-options.go35-132

Size Calculation

Encrypted objects are slightly larger than their plaintext counterparts due to DARE package overhead:

encrypted_size = plaintext_size + (num_packages * SSEDAREPackageMetaSize)
where num_packages = ceil(plaintext_size / SSEDAREPackageBlockSize)

The GetActualSize() method reverses this calculation to return the original plaintext size.

Sources: cmd/encryption-v1.go260-302