mirror of
https://github.com/linuxkit/linuxkit.git
synced 2025-07-26 04:03:11 +00:00
87 lines
3.5 KiB
Markdown
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.|
|