# Change the encryption key

Move a bucket's encryption to a KMS key of yours, or back to the platform key, without rewriting any object.

Every bucket is encrypted; this chooses the key that wraps the bucket's data key (see
[Encryption](encryption.md)). Changing it re-wraps that one data key, so every object, old and
new, follows the new key at once and nothing is rewritten. Replace _example-uploads_ with your
bucket's name and _0b5c3e9a-2f4d-4c8e-9a1b-7d6e5f4a3b2c_ with your KMS key's id.

**Important:**
With a KMS key, the key controls the data. Disable it and every read and write in the bucket is
refused until it is enabled again; delete it, or its imported material, and the objects cannot be
read again by anyone.

## Prerequisites

- Permission for `s3:PutEncryptionConfiguration` on the bucket. In the console, also `s3:GetBucket`
  to open the bucket (without it the bucket's page says "Access denied") and
  `s3:GetEncryptionConfiguration`: without it the tab says "Reading this bucket’s encryption needs
  s3:GetEncryptionConfiguration."; without the first, **Save** is unavailable and says
  `Needs s3:PutEncryptionConfiguration.`
- For a KMS key: `kms:Encrypt` on the key, and the key enabled.
- The bucket's current key still opens: a bucket whose KMS key is disabled cannot be moved off it
  until the key is enabled again.

## Change the key

**Console**
1. Open **Object Storage**, open the bucket, then choose **Encryption**.
2. Under **Change the key**, for **Encryption key**, choose a key under **Customer managed keys**,
   or **Platform-managed key (default)**.
3. Choose **Save**.

**Default encryption** shows the key under **Wrapped by** and the type (**SSE-KMS** or
**SSE-S3 (AES-256)**) under **Type**.

**CLI**
```sh
dcloud s3 bucket-encryption set example-uploads --kms-key-id 0b5c3e9a-2f4d-4c8e-9a1b-7d6e5f4a3b2c
```

Back to the platform key: `dcloud s3 bucket-encryption delete example-uploads`.

**API**
```http
PUT /s3/api/buckets/example-uploads/encryption
{ "kmsKeyId": "0b5c3e9a-2f4d-4c8e-9a1b-7d6e5f4a3b2c" }
```

`{ "kmsKeyId": null }` or `DELETE /s3/api/buckets/example-uploads/encryption` returns to the
platform key.

**Terraform**
```hcl
resource "dcloud_bucket_encryption" "uploads" {
  bucket     = dcloud_bucket.uploads.id
  kms_key_id = dcloud_kms_key.uploads.id
}
```

Destroying it returns the bucket to the platform key.

Over S3:

```sh
aws --profile dcloud --endpoint-url https://s3.<domain> s3api put-bucket-encryption \
  --bucket example-uploads --server-side-encryption-configuration \
  '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"<key id>"}}]}'
aws --profile dcloud --endpoint-url https://s3.<domain> s3api get-bucket-encryption --bucket example-uploads
```

`delete-bucket-encryption` returns the bucket to the platform key. Encryption itself cannot be
turned off.

## Result

The answer is `{ algorithm, kmsKeyId, active }`: `aws:kms` with the key, or `AES256` with
`kmsKeyId: null`. Reading the setting (`s3:GetEncryptionConfiguration`) also says whether the key
is `usable` now and, if not, the `problem`; the console then shows "The bucket’s KMS key cannot be
used: reads and writes are refused."

## If it is refused

With `409`:

- `KMS key … does not exist`, `KMS key … is not an encryption key`, `KMS key … is disabled` (or
  another status that is not enabled).
- `The KMS key that encrypts this bucket has been deleted; its objects cannot be read`.
- `The bucket key changed while this request ran; try again`.
- `A bucket the platform manages keeps its own encryption`.

Without `kms:Encrypt` on the key the request is refused with `403`.

## Related

- [Encryption](encryption.md)
- [Keys (KMS)](/docs/kms)
- `s3.bucket-encryption.set` · `dcloud s3 bucket-encryption set` · `dcloud_bucket_encryption`
