linuxkit/docs/encrypted-disk.md

Device encryption with dm-crypt

In the packages section you can find an image to setup dm-crypt encrypted devices in linuxkit-generated images.

Usage

The setup is a one time step during boot:

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:

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:

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

    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.