linuxkit/docs/encrypted-disk.md
Christian Wuerdig a9bc7372de Adding dm-crypt as core pkg
Signed-off-by: Christian Wuerdig <christian.wuerdig@gmail.com>
2019-01-18 11:56:18 +13:00

87 lines
3.5 KiB
Markdown

# Device encryption with dm-crypt
In the packages section you can find an image to setup dm-crypt encrypted devices in [linuxkit](https://github.com/linuxkit/linuxkit)-generated images.
## Usage
The setup is a one time step during boot:
```yaml
onboot:
- name: dm-crypt
image: linuxkit/dm-crypt:<hash>
command: ["/usr/bin/crypto", "dm_crypt_name", "/dev/sda1"]
- name: mount
image: linuxkit/mount:<hash>
command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
files:
- path: etc/dm-crypt/key
contents: "abcdefghijklmnopqrstuvwxyz123456"
```
The above will map `/dev/sda1` as an encrypted device under `/dev/mapper/dm_crypt_name` and mount it under `/var/secure_storage`
The `dm-crypt` container by default bind-mounts `/dev:/dev` and `/etc/dm-crypt:/etc/dm-crypt`. It expects the encryption key to be present in the file `/etc/dm-crypt/key`. You can pass an alternative location as encryption key which can be either a file path relative to `/etc/dm-crypt` or an absolute path.
Providing an alternative encryption key file name:
```yaml
onboot:
- name: dm-crypt
image: linuxkit/dm-crypt:<hash>
command: ["/usr/bin/crypto", "-k", "some_other_key", "dm_crypt_name", "/dev/sda1"]
- name: mount
image: linuxkit/mount:<hash>
command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
files:
- path: etc/dm-crypt/some_other_key
contents: "abcdefghijklmnopqrstuvwxyz123456"
```
Providing an alternative encryption key file name as absolute path:
```yaml
onboot:
- name: dm-crypt
image: linuxkit/dm-crypt:<hash>
command: ["/usr/bin/crypto", "-k", "/some/other/key", "dm_crypt_name", "/dev/sda1"]
binds:
- /dev:/dev
- /etc/dm-crypt/some_other_key:/some/other/key
- name: mount
image: linuxkit/mount:<hash>
command: ["/usr/bin/mountie", "/dev/mapper/dm_crypt_name", "/var/secure_storage"]
files:
- path: etc/dm-crypt/some_other_key
contents: "abcdefghijklmnopqrstuvwxyz123456"
```
Note that you have to also map `/dev:/dev` explicitly if you override the default bind-mounts.
The `dm-crypt` container
* Will create an `ext4` file system on the encrypted device if none is present.
* It will also initialize the encrypted device by filling it from `/dev/zero` prior to creating the filesystem. Which means if the device is being setup for the first time it might take a bit longer.
* Uses the `aes-cbc-essiv:sha256` cipher (it's explicitly specified in case the default ever changes)
* Consequently the encryption key is expected to be 32 bytes long, a random one can be created via
```shell
dd if=/dev/urandom of=dm-crypt.key bs=32 count=1
```
If you see the error `Cannot read requested amount of data.` next to the log message `Creating dm-crypt mapping for ...` then this means your keyfile doesn't contain enough data.
### Examples
There are two examples in the `examples/` folder:
1. `dm-crypt.yml` - formats an external disk and mounts it encrypted.
2. `dm-crypt-loop.yml` - mounts an encrypted loop device backed by a regular file sitting on an external disk
### Options
|Option|Default|Required|Notes|
|---|---|---|---|
|`-k` or `--key`|`key`|No|Encryption key file name. Must be either relative to `/etc/dm-crypt` or an absolute file path.|
|`-l` or `--luks`||No|Use LUKS format for encryption|
|`<dm_name>`||**Yes**|The device-mapper device name to use. The device will be mapped under `/dev/mapper/<dm_name>`|
|`<device>`||**Yes**|Device to encrypt.|