github/linuxkit
1
0
Fork 0
mirror of https://github.com/linuxkit/linuxkit.git synced 2025-09-01 23:18:41 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #3249 from chriswue/master

Browse Source 
Adding support to mount an encrypted filesystem
This commit is contained in:
Rolf Neugebauer
2019-01-18 01:28:50 +01:00
committed by GitHub
parent 6412cfa117 a9bc7372de
commit eeb2d546d1
22 changed files with 664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/encrypted-disk.md Normal file
View File

@@ -0,0 +1,86 @@
# 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.|

27
docs/losetup.md Normal file
View File

@@ -0,0 +1,27 @@
# LinuxKit losetup
Image to setup a loop device backed by a regular file in a [linuxkit](https://github.com/linuxkit/linuxkit)-generated image. The typical use case is to have a portable storage location which can be used to persist settings or other files. Can be combined with the `linuxkit/dm-crypt` package for protection.
## Usage
The setup is a one time step during boot:
```yaml
onboot:
- name: losetup
image: linuxkit/losetup:<hash>
command: ["/usr/bin/loopy", "-c", "/var/test.img"]
```
The above will associate the file `/var/test.img` with `/dev/loop0` and will also create it if it's not present.
The container by default bind-mounts `/var:/var` and `/dev:/dev`. Usually the loop-file will reside on external storage which should be typically mounted under `/var` hence the choice of the defaults. If the loop-file is located somewhere else and you need a different bind-mount for it then do not forget to explicitly bind-mount `/dev:/dev` as well or else `losetup` will fail.
### Options
|Option|Default|Required|Notes|
|---|---|---|---|
|`-c` or `--create`||No|Creates the file if not present. If `--create` is not specified and the file is missing then the loop setup will obviously fail.|
|`-s` or `--size`|10|No|If `--create` was specified and the file is not present then this sets the size in MiB of the created file. The file will be filled from `/dev/zero`.|
|`-d` or `--dev`|`/dev/loop0`|No|Loop device which should be associated with the file.|
|`<file>`||**Yes**|The file to use as backing storage.|