SSE Reference Documentation

Encryption Key Ownership

When configuring encryption using the PutBucketEncryption or PutObject S3 API calls, the SSEAlgorithm parameter controls the ownership of the master encryption keys – by the platform or by the user – and correspondingly the way the API behaves.

AES256

With SSEAlgorithm=AES256, ARTESCA owns and manages the master encryption keys. Users have no control over these keys. ARTESCA handles the key lifecycle, creating a key per bucket when encryption is first used.

The master key ID is never exposed to S3 users in API responses when using AES256.

aws:kms

With SSEAlgorithm=aws:kms, the account owns the master encryption keys. Users can either:

• Provide a specific key ID using the KMSMasterKeyID parameter (referred to as a “customer-configured master key”). The key must already exist in the KMS.

• Omit the key ID, in which case ARTESCA uses the bucket’s existing default master key, or requests the KMS to generate a new one if no key exists yet.

When using aws:kms, the master key ID (or its ARN) is returned in S3 API responses (PutObject, HeadObject, GetObject, CopyObject).

Customer-Configured Master Key

When using the aws:kms SSEAlgorithm, provide the ID of the master encryption key to use for a specific object or bucket through the KMSMasterKeyID parameter.

At bucket level (PutBucketEncryption): the specified key becomes the default for all objects uploaded to that bucket without their own key ID.

At object level (PutObject): the specified key overrides any bucket-level default for that specific object.

If no KMSMasterKeyID is provided:

• If the bucket has a configured default key, that key is used.

• Otherwise, ARTESCA creates a new master key in the KMS for the bucket.

Important

Regardless of the SSEAlgorithm chosen (AES256 or aws:kms), encryption keys are always stored in the configured backend: metadata for internal SSE, or the external KMS for external SSE. This differs from AWS, where SSEAlgorithm implicitly selects the backend (AES256 uses S3-managed storage and aws:kms uses AWS KMS), whereas ARTESCA uses the single pre-configured backend for both algorithms.

Encryption Behavior Matrix

The following table describes what happens for all 16 combinations of bucket-level and object-level encryption settings. This is the actual behavior verified against ARTESCA.

Column definitions:

• Bucket SSE Algo – the SSEAlgorithm value configured on the bucket using PutBucketEncryption. This is the bucket’s default encryption algorithm.

• Bucket Key ID – the KMSMasterKeyID value configured on the bucket using PutBucketEncryption. This is the bucket’s default master key.

• Object SSE Algo – the x-amz-server-side-encryption header sent with the PutObject request. This is per-object and overrides the bucket default.

• Object Key ID – the x-amz-server-side-encryption-aws-kms-key-id header sent with the PutObject request.

• Result – the encryption actually applied to the stored object:

  • No encryption – object stored unencrypted

  • AES256 – encrypted with ARTESCA-managed key

  • aws:kms (auto) – encrypted with aws:kms, using a key auto-created on first use

  • aws:kms (bucket) – encrypted with aws:kms, using the bucket’s configured key

  • aws:kms (custom) – encrypted with aws:kms, using the key specified in the request

#	Bucket SSE Algo	Bucket Key ID	Object SSE Algo	Object Key ID	Result
1	(none)	-	(none)	-	No encryption
2	(none)	-	AES256	-	AES256
3	(none)	-	aws:kms	-	aws:kms (auto)
4	(none)	-	aws:kms	custom-key-1	aws:kms (custom)
5	AES256	-	(none)	-	AES256
6	AES256	-	AES256	-	AES256
7	AES256	-	aws:kms	-	aws:kms (auto)
8	AES256	-	aws:kms	custom-key-1	aws:kms (custom)
9	aws:kms	-	(none)	-	aws:kms (auto)
10	aws:kms	-	AES256	-	AES256
11	aws:kms	-	aws:kms	-	aws:kms (auto)
12	aws:kms	-	aws:kms	custom-key-1	aws:kms (custom)
13	aws:kms	bucket-key	(none)	-	aws:kms (bucket)
14	aws:kms	bucket-key	AES256	-	AES256
15	aws:kms	bucket-key	aws:kms	-	aws:kms (bucket)
16	aws:kms	bucket-key	aws:kms	custom-key-2	aws:kms (custom)

Key rules:

• Object-level headers always override bucket defaults (rows 7-8, 10, 12, 14, 16)

• When no object-level header is set, the bucket default applies (rows 5, 9, 13)

• Providing a KMSMasterKeyID with AES256 is an error (InvalidArgument)

• When no encryption is configured at any level, objects are stored unencrypted (row 1)

Master Encryption Key ID Format

ARTESCA stores the master key ID in the object metadata using a Scality-specific ARN format that encodes which KMS was used to generate and store the key:

arn:scality:kms:<type>:<protocol>:<provider>:key/<keyId>

Component	Description
type	internal (no external KMS configured) or external (KMIP or AWS KMS).
protocol	The protocol used to interface with the KMS: file – internal, keys stored in metadata kmip – external, KMIP protocol aws_kms – external, AWS KMS API
provider	The configured providerName. For internal SSE, always scality. For external SSE, the value set in the Zenko CR (for example, thales, hashicorp, awsprod).
keyId	The key identifier from the KMS. For KMIP, this is typically a numeric ID assigned by the server. For AWS KMS, this may be an ARN itself.

Examples:

• Internal: arn:scality:kms:internal:file:scality:key/a1b2c3d4e5f6...

• KMIP (Thales): arn:scality:kms:external:kmip:thales:key/14

• KMIP (Thales preprod): arn:scality:kms:external:kmip:thalespreprod:key/14

• KMIP (Hashicorp): arn:scality:kms:external:kmip:hashicorp:key/27

• AWS KMS: arn:scality:kms:external:aws_kms:awsprod:key/arn:aws:kms:us-east-1:123456:key/abc

Provider Name Requirements

For KMIP, the providerName must use one of the following prefixes:

• thales – for Thales CipherTrust Manager (for example, thales, thalespreprod)

• hashicorp – for Hashicorp Vault (for example, hashicorp, hashicorpstaging)

• hytrust – for Hytrust KeyControl (for example, hytrust, hytrustprod)

The suffix after the prefix is a free-form alphanumeric string chosen by the administrator to distinguish environments (for example, thalesprod, thalespreprod). The suffix can also be omitted (for example, thales).

For AWS KMS, the providerName is an open lowercase alphanumeric string chosen by the administrator (for example, awsprod, awstest).

Warning

The providerName is embedded in every encrypted object’s metadata. If you change the providerName, all objects encrypted with the original name become unreadable until the original value is restored. ARTESCA matches the providerName in the stored ARN against the currently configured provider, and rejects the request if they do not match.

Controlling the ARN Format in API Responses

By default (noAwsArn: false), S3 API responses return the key ID in AWS-native format, which avoids confusion with third-party applications that expect standard AWS-style key identifiers. Setting noAwsArn: true makes ARTESCA return the full Scality-internal ARN (arn:scality:kms:external:aws_kms:...) instead, which can be useful to identify which KMS backend encrypted a given object after a migration.

For KMIP, the Scality ARN is always used because there is no native KMIP ARN format.

SSE and Access Control

SSE is transparent to IAM and access control. Encryption and decryption happen automatically inside ARTESCA – the S3 API behaves identically whether objects are encrypted or not.

• Any user with s3:GetObject permission receives the decrypted data. There is no per-user or per-key access control on encryption keys. This differs from AWS, where IAM policies can grant or deny access to specific KMS keys.

• Root users and IAM users experience the same encryption behavior. Keys are associated with buckets (or accounts), not with individual users.

• Cross-user access: if User B has permission to read objects in User A’s encrypted bucket, User B receives the decrypted content. Encryption does not add an authorization layer.

• Service accounts (used internally by ARTESCA for replication, lifecycle, and so on) can also read encrypted objects – they follow the same transparent decryption path.

Bucket Policy SSE Condition Keys

ARTESCA does not currently support SSE condition keys in bucket policies:

• s3:x-amz-server-side-encryption

• s3:x-amz-server-side-encryption-aws-kms-key-id

Attempting to use these condition keys in a PutBucketPolicy call is rejected with a MalformedPolicy error. This means bucket policies cannot currently be used to enforce that uploads must use encryption.

Replication of SSE-Encrypted Objects

Warning

The SourceSelectionCriteria.SseKmsEncryptedObjects field in replication configuration is accepted but not enforced: both encrypted and unencrypted objects matching the replication rule are replicated, regardless of the value of this field. This differs from AWS S3 behavior.