# Encryption

How every object is encrypted at rest under its bucket's own data key, wrapped by the platform key or a KMS key of yours, and what that means for S3 clients.

Each bucket has its own random 256-bit data key. Every write hands that key to the object store,
which encrypts the object with it (AES-256); the data key itself is stored only wrapped, by one of:

| Wrapping key          | S3 name   | Console type     | Choose it                                                                             |
| --------------------- | --------- | ---------------- | ------------------------------------------------------------------------------------- |
| The platform key      | `AES256`  | SSE-S3 (AES-256) | the default, nothing to do                                                            |
| A KMS key of your own | `aws:kms` | SSE-KMS          | at creation, or later (see [Change the encryption key](change-the-encryption-key.md)) |

A new bucket gets its data key when it is created. A bucket created before encryption existed gets
its data key on its next write (its **State** shows "The data key is made on the next write.");
objects written before that stay unencrypted until they are written again. Copying an object onto
itself encrypts it:

```sh
aws --profile dcloud --endpoint-url https://s3.<domain> s3 cp s3://example-uploads/report.pdf \
  s3://example-uploads/report.pdf --metadata-directive REPLACE
```

## What clients see

- Range reads, multipart uploads, copies and presigned URLs work as before.
- Responses for an encrypted object carry `x-amz-server-side-encryption` (`AES256`, or `aws:kms`
  with the key id).
- Any other algorithm, such as `aws:kms:dsse`, is refused with `InvalidArgument` "Server-side
  encryption … is not supported; use AES256 or aws:kms". `AES256` is always accepted.
- A write that asks for `aws:kms` with a key other than the bucket's is refused with
  `InvalidArgument` "Objects are encrypted under the bucket’s KMS key; a different key per object
  is not supported". On a bucket with the platform key, `aws:kms` is refused with "This bucket
  encrypts with the platform key; set a KMS key as its default encryption to use aws:kms".
- Your own SSE-C key (`x-amz-server-side-encryption-customer-*` headers) replaces the bucket's for
  that object; you then need it for every read.
- A copy of an encrypted object streams through the platform, so a large copy takes as long as
  reading and writing it.

## A KMS key controls the data

Disable the KMS key and every read and write in the bucket is refused with `KMS.DisabledException`
within 30 seconds, until it is enabled again. Delete it, or its imported material, and the objects
cannot be read again by anyone. Removing the encryption configuration returns the bucket to the
platform key, as on AWS; encryption itself cannot be turned off.

## Buckets the platform writes

A database's backup bucket is outside this scheme: the database encrypts each backup file on its
own machine, with a key of its own, before upload. The bucket's **Encryption** tab shows **Who
encrypts**: "The platform service that writes it".

## Related

- [Change the encryption key](change-the-encryption-key.md)
- [Security](security.md)
