^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) dm-crypt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Device-Mapper's "crypt" target provides transparent encryption of block devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) using the kernel crypto API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) For a more detailed description of supported parameters see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Parameters::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) <cipher> <key> <iv_offset> <device path> \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) <offset> [<#opt_params> <opt_params>]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) <cipher>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Encryption cipher, encryption mode and Initial Vector (IV) generator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) The cipher specifications format is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) cipher[:keycount]-chainmode-ivmode[:ivopts]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) aes-cbc-essiv:sha256
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) aes-xts-plain64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) serpent-xts-plain64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Cipher format also supports direct specification with kernel crypt API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) format (selected by capi: prefix). The IV specification is the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) as for the first format type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) This format is mainly used for specification of authenticated modes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) The crypto API cipher specifications format is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) capi:cipher_api_spec-ivmode[:ivopts]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) capi:cbc(aes)-essiv:sha256
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) capi:xts(aes)-plain64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Examples of authenticated modes::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) capi:gcm(aes)-random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) capi:authenc(hmac(sha256),xts(aes))-random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) capi:rfc7539(chacha20,poly1305)-random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) The /proc/crypto contains a list of curently loaded crypto modes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) <key>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Key used for encryption. It is encoded either as a hexadecimal number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) or it can be passed as <key_string> prefixed with single colon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) character (':') for keys residing in kernel keyring service.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) You can only use key sizes that are valid for the selected cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) in combination with the selected iv mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) Note that for some iv modes the key string can contain additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) keys (for example IV seed) so the key contains more parts concatenated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) into a single string.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) <key_string>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) The kernel keyring key is identified by string in following format:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) <key_size>:<key_type>:<key_description>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) <key_size>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) The encryption key size in bytes. The kernel key payload size must match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) the value passed in <key_size>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) <key_type>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Either 'logon', 'user' or 'encrypted' kernel key type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) <key_description>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) The kernel keyring key description crypt target should look for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) when loading key of <key_type>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) <keycount>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Multi-key compatibility mode. You can define <keycount> keys and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) then sectors are encrypted according to their offsets (sector 0 uses key0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) sector 1 uses key1 etc.). <keycount> must be a power of two.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) <iv_offset>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) The IV offset is a sector count that is added to the sector number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) before creating the IV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) <device path>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) This is the device that is going to be used as backend and contains the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) encrypted data. You can specify it as a path like /dev/xxx or a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) number <major>:<minor>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) <offset>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Starting sector within the device where the encrypted data begins.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) <#opt_params>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Number of optional parameters. If there are no optional parameters,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) the optional paramaters section can be skipped or #opt_params can be zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Otherwise #opt_params is the number of following arguments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Example of optional parameters section:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) 3 allow_discards same_cpu_crypt submit_from_crypt_cpus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) allow_discards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Block discard requests (a.k.a. TRIM) are passed through the crypt device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) The default is to ignore discard requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) WARNING: Assess the specific security risks carefully before enabling this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) option. For example, allowing discards on encrypted devices may lead to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) the leak of information about the ciphertext device (filesystem type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) used space etc.) if the discarded blocks can be located easily on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) device later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) same_cpu_crypt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Perform encryption using the same cpu that IO was submitted on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) The default is to use an unbound workqueue so that encryption work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) is automatically balanced between available CPUs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) submit_from_crypt_cpus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Disable offloading writes to a separate thread after encryption.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) There are some situations where offloading write bios from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) encryption threads to a single thread degrades performance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) significantly. The default is to offload write bios to the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) thread because it benefits CFQ to have writes submitted using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) same context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) no_read_workqueue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Bypass dm-crypt internal workqueue and process read requests synchronously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) no_write_workqueue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Bypass dm-crypt internal workqueue and process write requests synchronously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) This option is automatically enabled for host-managed zoned block devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) (e.g. host-managed SMR hard-disks).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) integrity:<bytes>:<type>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) The device requires additional <bytes> metadata per-sector stored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) in per-bio integrity structure. This metadata must by provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) by underlying dm-integrity target.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) The <type> can be "none" if metadata is used only for persistent IV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) For Authenticated Encryption with Additional Data (AEAD)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) the <type> is "aead". An AEAD mode additionally calculates and verifies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) integrity for the encrypted device. The additional space is then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) used for storing authentication tag (and persistent IV if needed).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) sector_size:<bytes>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) Use <bytes> as the encryption unit instead of 512 bytes sectors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) This option can be in range 512 - 4096 bytes and must be power of two.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Virtual device will announce this size as a minimal IO and logical sector.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) iv_large_sectors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) IV generators will use sector number counted in <sector_size> units
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) instead of default 512 bytes sectors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) For example, if <sector_size> is 4096 bytes, plain64 IV for the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) sector will be 8 (without flag) and 1 if iv_large_sectors is present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) The <iv_offset> must be multiple of <sector_size> (in 512 bytes units)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) if this flag is specified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Example scripts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) LUKS (Linux Unified Key Setup) is now the preferred way to set up disk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) encryption with dm-crypt using the 'cryptsetup' utility, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) https://gitlab.com/cryptsetup/cryptsetup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) #!/bin/sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) # Create a crypt device using dmsetup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) dmsetup create crypt1 --table "0 `blockdev --getsz $1` crypt aes-cbc-essiv:sha256 babebabebabebabebabebabebabebabe 0 $1 0"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) #!/bin/sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) # Create a crypt device using dmsetup when encryption key is stored in keyring service
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) dmsetup create crypt2 --table "0 `blockdev --getsize $1` crypt aes-cbc-essiv:sha256 :32:logon:my_prefix:my_key 0 $1 0"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) #!/bin/sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) # Create a crypt device using cryptsetup and LUKS header with default cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) cryptsetup luksFormat $1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) cryptsetup luksOpen $1 crypt1
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags