# Use encrypted volumes

How an encrypted volume opens on its instance, how to format and mount it, rotate its key, and install the volume helper on an older instance.

A new volume is encrypted (LUKS2) unless you create it with **Encrypt the volume** cleared
(`"encrypted": false`). It gets its own random key, wrapped by the platform key, or by one of your
KMS keys if you choose one (`"kmsKeyId"`). An instance launched in a Deutsche Cloud region carries a
small volume helper next to your user data, unless your user data leaves no room for it within the
32 KiB user-data limit; instances on your own hosts do not carry it. When an encrypted volume is
attached, the helper asks the control plane for its key and opens it as
`/dev/mapper/ews-vol-<number>`, where `<number>` is the one in the plain device path
`/dev/disk/by-id/scsi-0HC_Volume_<number>`. On a new, empty volume it writes the LUKS2 header first;
it never formats a device that already holds data that is not LUKS.

## Prerequisites

- Creating needs `ec2:CreateVolume`, and `kms:Encrypt` on a KMS key you choose. A KMS key with an
  unencrypted volume is refused with `400` "A KMS key only applies to an encrypted volume".
- Rotating needs `ec2:RotateVolumeKey`; installing the helper `ec2:InstallVolumeHelper`.

## Format and mount it

After [attaching it](create-and-attach-a-volume.md), use the mapper device as you would the raw one.
In `/etc/fstab`, add `_netdev,nofail`, because opening needs the network:

```sh
sudo mkfs.ext4 /dev/mapper/ews-vol-12345678
echo '/dev/mapper/ews-vol-12345678 /data ext4 _netdev,nofail 0 2' | sudo tee -a /etc/fstab
sudo mkdir -p /data && sudo mount /data
```

Before detaching, unmount the filesystem and run `sudo cryptsetup close ews-vol-<number>`.

## What the encryption protects

The key is released only to the instance the volume is attached to, from that instance's own
address. A detached volume, or a copy of its blocks, is unreadable. Deleting the volume deletes the
key. If you chose a KMS key, the key is released only while that KMS key is enabled: disabling or
deleting it makes the volume unopenable. An opened volume is readable to whoever is root on the
instance: the encryption protects the data from outside the instance, not from inside it.

## Rotate the key

**Console:** not available. The console has no key rotation; use the CLI or the API.

**CLI**
```sh
dcloud ec2 volumes rotate-key vol-1a2b3c4d
```

**API**
```http
POST /ec2/api/volumes/vol-1a2b3c4d/rotate-key
```

**Terraform:** not available. A rotation is an action, not a resource.

The answer is `202` with the volume's key version and `rotationPending`. The helper on the instance
it is attached to checks every five minutes, adds the new key and removes the old one; the volume
stays mounted. A detached volume finishes when it is next attached and opened. A rotation replaces
the passphrase that unlocks the volume; the data itself is not re-encrypted. An unencrypted volume
is refused with `409` "The volume is not encrypted", and a second rotation before the first has
finished with `409` "A key rotation is already in progress".

## Install the volume helper on an older instance

An instance launched without the volume helper (before it existed, or with user data that left no
room for it) cannot open an encrypted volume, and attaching one is refused with `409` ("… was
launched without the volume helper, so it cannot open an encrypted volume. …"). A terminated or
unknown instance answers `404` "Instance not found".

**Console:** not available. The script is handed out by the API and the CLI.

**CLI**
```sh
dcloud ec2 instances install-volume-helper i-3f9a2c07 --json > helper.json
jq -r .data.script helper.json > ews-volume-helper.sh
sudo bash ews-volume-helper.sh
```

**API**
```http
POST /ec2/api/instances/i-3f9a2c07/volume-helper
```

Run `data.script` as root on the instance.

**Terraform:** not available. The helper is installed on the machine, not through a resource.

The script installs the helper and reports in; it prints "… volume helper installed; encrypted
volumes can now be attached to this instance." If it cannot reach the console it says so and exits
with an error: run it again. `data.installed` in the answer says whether the instance had already
reported in before this request. Running the script again does no harm. The script carries a credential for
that instance alone: anything that can read it on the instance can ask for the keys of volumes
attached to it, from that instance. Otherwise, launch a new instance, or create the volume with
`"encrypted": false`.

To move data from an unencrypted volume, attach a new encrypted volume next to it, copy
(`rsync -aHAX /old/ /new/`), switch the mount and delete the old volume. Nothing is encrypted in
place.

## Related

- [Create and attach a volume](create-and-attach-a-volume.md)
- `ec2.volumes.rotate-key` · `dcloud ec2 instances install-volume-helper` · `dcloud_volume`
