| 1 | ==============
|
| 2 | dm-inlinecrypt
|
| 3 | ==============
|
| 4 |
|
| 5 | Device-Mapper's "inlinecrypt" target provides transparent encryption of block devices
|
| 6 | using the inline encryption hardware.
|
| 7 |
|
| 8 | For a more detailed description of inline encryption, see:
|
| 9 | https://docs.kernel.org/block/inline-encryption.html
|
| 10 |
|
| 11 | Parameters::
|
| 12 |
|
| 13 | <cipher> <key> <iv_offset> <device path> \
|
| 14 | <offset> [<#opt_params> <opt_params>]
|
| 15 |
|
| 16 | <cipher>
|
| 17 | Encryption cipher type.
|
| 18 |
|
| 19 | The cipher specifications format is::
|
| 20 |
|
| 21 | cipher
|
| 22 |
|
| 23 | Examples::
|
| 24 |
|
| 25 | aes-xts-plain64
|
| 26 |
|
| 27 | The cipher type corresponds to the encryption modes supported by
|
| 28 | inline crypto in the block layer. Currently, only
|
| 29 | BLK_ENCRYPTION_MODE_AES_256_XTS (i.e. aes-xts-plain64) is supported.
|
| 30 |
|
| 31 | <key>
|
| 32 | Key used for encryption. It is encoded either as a hexadecimal number
|
| 33 | or it can be passed as <key_string> prefixed with single colon
|
| 34 | character (':') for keys residing in kernel keyring service.
|
| 35 | You can only use key sizes that are valid for the selected cipher.
|
| 36 | Note that the size in bytes of a valid key must be in below range.
|
| 37 |
|
| 38 | [BLK_CRYPTO_KEY_TYPE_RAW, BLK_CRYPTO_KEY_TYPE_HW_WRAPPED]
|
| 39 |
|
| 40 | <key_string>
|
| 41 | The kernel keyring key is identified by string in following format:
|
| 42 | <key_size>:<keyring_type>:<key_description>.
|
| 43 |
|
| 44 | <key_size>
|
| 45 | The encryption key size in bytes. The kernel key payload size must match
|
| 46 | the value passed in <key_size>.
|
| 47 |
|
| 48 | <keyring_type>
|
| 49 | The type of the key inside the kernel keyring. It can be either 'logon',
|
| 50 | or 'trusted' kernel key type.
|
| 51 |
|
| 52 | <key_description>
|
| 53 | The kernel keyring key description inlinecrypt target should look for
|
| 54 | when loading key of <keyring_type>.
|
| 55 |
|
| 56 | <iv_offset>
|
| 57 | The IV offset is a sector count that is added to the sector number
|
| 58 | before creating the IV.
|
| 59 |
|
| 60 | <device path>
|
| 61 | This is the device that is going to be used as backend and contains the
|
| 62 | encrypted data. You can specify it as a path like /dev/xxx or a device
|
| 63 | number <major>:<minor>.
|
| 64 |
|
| 65 | <offset>
|
| 66 | Starting sector within the device where the encrypted data begins.
|
| 67 |
|
| 68 | <#opt_params>
|
| 69 | Number of optional parameters. If there are no optional parameters,
|
| 70 | the optional parameters section can be skipped or #opt_params can be zero.
|
| 71 | Otherwise #opt_params is the number of following arguments.
|
| 72 |
|
| 73 | Example of optional parameters section:
|
| 74 | keytype:raw allow_discards sector_size:4096 iv_large_sectors
|
| 75 |
|
| 76 | <key_type>
|
| 77 | The type of the key as seen by the block layer, either standard or
|
| 78 | hardware-wrapped. The string is supplied in the table as <keytype:raw>
|
| 79 | or <keytype:hw-wrapped>.
|
| 80 |
|
| 81 | allow_discards
|
| 82 | Block discard requests (a.k.a. TRIM) are passed through the inlinecrypt
|
| 83 | device. The default is to ignore discard requests.
|
| 84 |
|
| 85 | WARNING: Assess the specific security risks carefully before enabling this
|
| 86 | option. For example, allowing discards on encrypted devices may lead to
|
| 87 | the leak of information about the ciphertext device (filesystem type,
|
| 88 | used space etc.) if the discarded blocks can be located easily on the
|
| 89 | device later.
|
| 90 |
|
| 91 | sector_size:<bytes>
|
| 92 | Use <bytes> as the encryption unit instead of 512 bytes sectors.
|
| 93 | This option can be in range 512 - 4096 bytes and must be power of two.
|
| 94 | Virtual device will announce this size as a minimal IO and logical sector.
|
| 95 |
|
| 96 | iv_large_sectors
|
| 97 | Use <sector_size>-based sector numbers for IV generation instead of
|
| 98 | 512-byte sectors.
|
| 99 |
|
| 100 | For dm-inlinecrypt, this flag must be specified when <sector_size>
|
| 101 | is larger than 512 bytes. The legacy 512-byte-based IV behavior is
|
| 102 | not supported.
|
| 103 |
|
| 104 | When specified, if <sector_size> is 4096 bytes, plain64 IV for the
|
| 105 | second sector will be 1, and <iv_offset> must be a multiple of
|
| 106 | <sector_size> (in 512-byte units).
|
| 107 |
|
| 108 | Example scripts
|
| 109 | ===============
|
| 110 | Currently, dm-inlinecrypt devices must be set up directly using dmsetup.
|
| 111 | There is no userspace support yet to integrate dm-inlinecrypt with LUKS
|
| 112 | or cryptsetup. In particular, cryptsetup currently only supports
|
| 113 | dm-crypt, and cannot be used to create dm-inlinecrypt mappings.
|
| 114 |
|
| 115 | The following examples demonstrate how to create dm-inlinecrypt devices
|
| 116 | using dmsetup
|
| 117 |
|
| 118 | ::
|
| 119 |
|
| 120 | #!/bin/sh
|
| 121 | # Create a inlinecrypt device using dmsetup
|
| 122 | dmsetup create inlinecrypt1 --table "0 `blockdev --getsz $1` inlinecrypt aes-xts-plain64 babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0 0 $1 0 1 keytype:raw"
|
| 123 |
|
| 124 | ::
|
| 125 |
|
| 126 | #!/bin/sh
|
| 127 | # Create a inlinecrypt device using dmsetup when encryption key is stored in keyring service
|
| 128 | dmsetup create inlinecrypt2 --table "0 `blockdev --getsz $1` inlinecrypt aes-xts-plain64 :64:logon:fde:dminlinecrypt_test_key 0 0 $1 0 1 keytype:raw"
|
| 129 |
|