eessppeelllloo/cryptsetup
1
0
Fork 0
mirror of https://gitlab.com/cryptsetup/cryptsetup.git synced 2025-12-05 16:00:05 +01:00
Code Issues Packages Projects Releases Wiki Activity

man: Do not wrap sentences in man pages.

Browse Source 
This helps to use external tools for language checking.
This commit is contained in:
Milan Broz
2025-07-09 15:23:15 +02:00
parent a52e1aadca
commit 1438140ce3
31 changed files with 1010 additions and 1697 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
man/common_footer.adoc
View File

@@ -1,7 +1,6 @@
== REPORTING BUGS
Report bugs at mailto:cryptsetup@lists.linux.dev[cryptsetup mailing list]
or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[Issues project section].
Report bugs at mailto:cryptsetup@lists.linux.dev[cryptsetup mailing list] or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[Issues project section].
Please attach output of the failed command with --debug option added.

976
man/common_options.adoc
View File

File diff suppressed because it is too large Load Diff

24
man/cryptsetup-benchmark.8.adoc
View File

@@ -16,26 +16,20 @@ cryptsetup-benchmark - benchmarks ciphers and KDF
== DESCRIPTION
Benchmarks ciphers and KDF (key derivation function). Without
parameters, it tries to measure few common configurations.
Benchmarks ciphers and KDF (key derivation function).
Without parameters, it tries to measure few common configurations.
To benchmark other ciphers or modes, you need to specify --cipher and
--key-size options.
To benchmark other ciphers or modes, you need to specify --cipher and --key-size options.
To benchmark PBKDF you need to specify --pbkdf or --hash with optional
cost parameters --iter-time, --pbkdf-memory or --pbkdf-parallel.
To benchmark PBKDF you need to specify --pbkdf or --hash with optional cost parameters --iter-time, --pbkdf-memory or --pbkdf-parallel.
*NOTE:* This benchmark uses memory only and is only informative. You
cannot directly predict real storage encryption speed from it.
*NOTE:* This benchmark uses memory only and is only informative.
You cannot directly predict real storage encryption speed from it.
For testing block ciphers, this benchmark requires kernel userspace
crypto API to be available (introduced in Linux kernel 2.6.38). If you
are configuring kernel yourself, enable "User-space interface for
symmetric key cipher algorithms" in "Cryptographic API" section
(CRYPTO_USER_API_SKCIPHER .config option).
For testing block ciphers, this benchmark requires kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38).
If you are configuring kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
*<options>* can be [--cipher, --key-size, --hash, --pbkdf, --iter-time,
--pbkdf-memory, --pbkdf-parallel].
*<options>* can be [--cipher, --key-size, --hash, --pbkdf, --iter-time, --pbkdf-memory, --pbkdf-parallel].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

15
man/cryptsetup-bitlkDump.8.adoc
View File

@@ -18,17 +18,14 @@ cryptsetup-bitlkDump - dump the header information of a BITLK (BitLocker compati
Dump the header information of a BITLK (BitLocker compatible) device.
If the --dump-volume-key option is used, the BITLK device volume key
is dumped instead of header information. You have to provide password
or keyfile to dump volume key.
If the --dump-volume-key option is used, the BITLK device volume key is dumped instead of header information.
You have to provide password or keyfile to dump volume key.
Beware that the volume key can be used to decrypt the data stored in
the container without a passphrase.
This means that if the volume key is compromised, the whole device has
to be erased to prevent further access. Use this option carefully.
Beware that the volume key can be used to decrypt the data stored in the container without a passphrase.
This means that if the volume key is compromised, the whole device has to be erased to prevent further access.
Use this option carefully.
*<options>* can be [--dump-volume-key, --volume-key-file, --key-file,
--keyfile-offset, --keyfile-size, --timeout].
*<options>* can be [--dump-volume-key, --volume-key-file, --key-file, --keyfile-offset, --keyfile-size, --timeout].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

8
man/cryptsetup-close.8.adoc
View File

@@ -16,13 +16,9 @@ cryptsetup-close - removes the existing mapping <name> (and the associated key)
== DESCRIPTION
Removes the existing mapping <name> and wipes the key from kernel
memory.
Removes the existing mapping <name> and wipes the key from kernel memory.
For backward compatibility, there are *close* command aliases: *remove*,
*plainClose*, *luksClose*, *loopaesClose*, *tcryptClose*, *bitlkClose*
(all behave exactly the same, device type is determined automatically
from the active device).
For backward compatibility, there are *close* command aliases: *remove*, *plainClose*, *luksClose*, *loopaesClose*, *tcryptClose*, *bitlkClose* (all behave exactly the same, device type is determined automatically from the active device).
*<options>* can be [--deferred, --cancel-deferred, --header, --disable-locks].

11
man/cryptsetup-config.8.adoc
View File

@@ -16,15 +16,12 @@ cryptsetup-config - set permanent configuration options (store to LUKS header)
== DESCRIPTION
Set permanent configuration options (store to LUKS header). The _config_
command is supported only for LUKS2.
Set permanent configuration options (store to LUKS header).
The _config_ command is supported only for LUKS2.
The permanent options can be --priority to set priority (normal,
prefer, ignore) for keyslot (specified by --key-slot) or --label and
--subsystem.
The permanent options can be --priority to set priority (normal, prefer, ignore) for keyslot (specified by --key-slot) or --label and --subsystem.
*<options>* can be [--priority, --label, --subsystem, --key-slot,
--header, --disable-locks].
*<options>* can be [--priority, --label, --subsystem, --key-slot, --header, --disable-locks].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

23
man/cryptsetup-convert.8.adoc
View File

@@ -16,26 +16,21 @@ cryptsetup-convert - converts the device between LUKS1 and LUKS2 format
== DESCRIPTION
Converts the device between LUKS1 and LUKS2 format (if possible). The
conversion will not be performed if there is an additional LUKS2 feature
or LUKS1 has unsupported header size.
Converts the device between LUKS1 and LUKS2 format (if possible).
The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has unsupported header size.
For conversion from LUKS2 to LUKS1, all active keyslots must use the PBKDF2
key-derivation function. The PBKDF2 and anti-forensic filter (AF) hash must
be the same as the hash used in the digest.
For conversion from LUKS2 to LUKS1, all active keyslots must use the PBKDF2 key-derivation function.
The PBKDF2 and anti-forensic filter (AF) hash must be the same as the hash used in the digest.
All keyslot numbers must be lower than 8 (LUKS1 maximum slot number).
There must be at least one active keyslot and no unbound or reencryption keyslots.
Conversion (both directions) must be performed on inactive device. There
must not be active dm-crypt mapping established for LUKS header
requested for conversion.
Conversion (both directions) must be performed on inactive device.
There must not be active dm-crypt mapping established for LUKS header requested for conversion.
The *--type* option is mandatory with the following accepted values: _luks1_ or
_luks2_.
The *--type* option is mandatory with the following accepted values: _luks1_ or _luks2_.
*WARNING:* The _convert_ action can destroy the LUKS header in the case
of a crash during conversion or if a media error occurs. Always create a
header backup before performing this operation!
*WARNING:* The _convert_ action can destroy the LUKS header in the case of a crash during conversion or if a media error occurs.
Always create a header backup before performing this operation!
*<options>* can be [--header, --type, --disable-locks].

8
man/cryptsetup-erase.8.adoc
View File

@@ -18,15 +18,11 @@ cryptsetup-erase, cryptsetup-luksErase - erase all keyslots
== DESCRIPTION
Erase all keyslots and make the LUKS container permanently inaccessible.
Unless the device is configured with HW OPAL support you do not need to
provide any password for this operation.
Unless the device is configured with HW OPAL support you do not need to provide any password for this operation.
*WARNING:* This operation is irreversible.
*WARNING:* with --hw-opal-factory-reset ALL data is lost on the device,
regardless of the partition it is ran on, if any, and regardless of any LUKS2
header backup, and does not require a valid LUKS2 header to be present on the
device to run.
*WARNING:* with --hw-opal-factory-reset ALL data is lost on the device, regardless of the partition it is ran on, if any, and regardless of any LUKS2 header backup, and does not require a valid LUKS2 header to be present on the device to run.
*<options>* can be [--header, --disable-locks, --hw-opal-factory-reset, --key-file].

15
man/cryptsetup-fvault2Dump.8.adoc
View File

@@ -18,17 +18,14 @@ cryptsetup-fvault2Dump - dump the header information of a FVAULT2 (FileVault2 co
Dump the header information of a FVAULT2 (FileVault2 compatible) device.
If the --dump-volume-key option is used, the FVAULT2 device volume key
is dumped instead of header information. You have to provide password
or keyfile to dump volume key.
If the --dump-volume-key option is used, the FVAULT2 device volume key is dumped instead of header information.
You have to provide password or keyfile to dump volume key.
Beware that the volume key can be used to decrypt the data stored in
the container without a passphrase.
This means that if the volume key is compromised, the whole device has
to be erased to prevent further access. Use this option carefully.
Beware that the volume key can be used to decrypt the data stored in the container without a passphrase.
This means that if the volume key is compromised, the whole device has to be erased to prevent further access.
Use this option carefully.
*<options>* can be [--dump-volume-key, --volume-key-file, --key-file,
--keyfile-offset, --keyfile-size, --timeout].
*<options>* can be [--dump-volume-key, --volume-key-file, --key-file, --keyfile-offset, --keyfile-size, --timeout].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

32
man/cryptsetup-luksAddKey.8.adoc
View File

@@ -16,29 +16,20 @@ cryptsetup-luksAddKey - add a new passphrase
== DESCRIPTION
Adds a keyslot protected by a new passphrase. An existing passphrase
must be supplied interactively, via --key-file or LUKS2 token (plugin).
Alternatively to existing passphrase user may pass directly volume key
(via --volume-key-file or --volume-key-keyring). The new passphrase to be added
can be specified interactively, read from the file given as the positional
argument (also via --new-keyfile parameter) or via LUKS2 token.
Adds a keyslot protected by a new passphrase.
An existing passphrase must be supplied interactively, via --key-file or LUKS2 token (plugin).
Alternatively to existing passphrase user may pass directly volume key (via --volume-key-file or --volume-key-keyring).
The new passphrase to be added can be specified interactively, read from the file given as the positional argument (also via --new-keyfile parameter) or via LUKS2 token.
*NOTE:* with --unbound option the action creates new unbound LUKS2
keyslot. The keyslot cannot be used for device activation. If you don't
pass new key via --volume-key-file option, new random key is generated.
*NOTE:* with --unbound option the action creates new unbound LUKS2 keyslot.
The keyslot cannot be used for device activation.
If you don't pass new key via --volume-key-file option, new random key is generated.
Existing passphrase for any active keyslot is not required.
*NOTE:* some parameters are effective only if used with LUKS2 format
that supports per-keyslot parameters. For LUKS1, PBKDF type and hash
algorithm is always the same for all keyslots.
*NOTE:* some parameters are effective only if used with LUKS2 format that supports per-keyslot parameters.
For LUKS1, PBKDF type and hash algorithm is always the same for all keyslots.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot,
--new-key-slot, --volume-key-file, --volume-key-keyring, --force-password,
--hash, --header, --disable-locks, --iter-time, --pbkdf,
--pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --unbound, --type,
--keyslot-cipher, --keyslot-key-size, --key-size, --timeout, --token-id,
--token-type, --token-only, --new-token-id, --verify-passphrase, --external-tokens-path].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot, --new-key-slot, --volume-key-file, --volume-key-keyring, --force-password, --hash, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --unbound, --type, --keyslot-cipher, --keyslot-key-size, --key-size, --timeout, --token-id, --token-type, --token-only, --new-token-id, --verify-passphrase, --external-tokens-path].
include::man/common_options.adoc[]
@@ -63,8 +54,7 @@ Add new keyslot using interactive passphrase prompt for existing keyslot, readin
*cryptsetup luksAddKey --new-keyfile key_file /dev/device* or
*cryptsetup luksAddKey /dev/device key_file*
Add new keyslot using volume stored in volume_key_file and LUKS2 token in slot 5 to get new keyslot passphrase (token in slot 5 must exist
and respective token plugin must be available):
Add new keyslot using volume stored in volume_key_file and LUKS2 token in slot 5 to get new keyslot passphrase (token in slot 5 must exist and respective token plugin must be available):
*cryptsetup luksAddKey --volume-key-file volume_key_file --new-token-id 5 /dev/device*

38
man/cryptsetup-luksChangeKey.8.adoc
View File

@@ -16,37 +16,23 @@ cryptsetup-luksChangeKey - change an existing passphrase
== DESCRIPTION
Changes an existing passphrase. The passphrase to be changed must be
supplied interactively or via --key-file. The new passphrase can be
supplied interactively or in a file given as the positional argument.
Changes an existing passphrase.
The passphrase to be changed must be supplied interactively or via --key-file.
The new passphrase can be supplied interactively or in a file given as the positional argument.
If a key-slot is specified (via --key-slot), the passphrase for that
key-slot must be given and the new passphrase will overwrite the
specified key-slot. If no key-slot is specified and there is still a
free key-slot, then the new passphrase will be put into a free key-slot
before the key-slot containing the old passphrase is purged. If there is
no free key-slot, then the key-slot with the old passphrase is
overwritten directly.
If a key-slot is specified (via --key-slot), the passphrase for that key-slot must be given and the new passphrase will overwrite the specified key-slot.
If no key-slot is specified and there is still a free key-slot, then the new passphrase will be put into a free key-slot before the key-slot containing the old passphrase is purged.
If there is no free key-slot, then the key-slot with the old passphrase is overwritten directly.
*WARNING:* If a key-slot is overwritten, a media failure during this
operation can cause the overwrite to fail after the old passphrase has
been wiped and make the LUKS container inaccessible. LUKS2 mitigates
that by never overwriting existing keyslot area as long as there's
a free space in keyslots area at least for one more LUKS2 keyslot.
*WARNING:* If a key-slot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped and make the LUKS container inaccessible.
LUKS2 mitigates that by never overwriting existing keyslot area as long as there's a free space in keyslots area at least for one more LUKS2 keyslot.
*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g.
to recover from a leak) you need to use them in that order to not leak
the new volume key.
*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g. to recover from a leak) you need to use them in that order to not leak the new volume key.
*NOTE:* some parameters are effective only if used with LUKS2 format
that supports per-keyslot parameters. For LUKS1, PBKDF type and hash
algorithm is always the same for all keyslots.
*NOTE:* some parameters are effective only if used with LUKS2 format that supports per-keyslot parameters.
For LUKS1, PBKDF type and hash algorithm is always the same for all keyslots.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations,
--pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot,
--force-password, --hash, --header, --disable-locks, --type,
--keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --new-keyfile-offset, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --new-keyfile-size, --key-slot, --force-password, --hash, --header, --disable-locks, --type, --keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

25
man/cryptsetup-luksConvertKey.8.adoc
View File

@@ -16,26 +16,17 @@ cryptsetup-luksConvertKey - converts an existing LUKS2 keyslot to new PBKDF para
== DESCRIPTION
Converts an existing LUKS2 keyslot to new PBKDF parameters. The
passphrase for keyslot to be converted must be supplied interactively or
via --key-file. If no --pbkdf parameters are specified LUKS2 default
PBKDF values will apply.
Converts an existing LUKS2 keyslot to new PBKDF parameters.
The passphrase for keyslot to be converted must be supplied interactively or via --key-file.
If no --pbkdf parameters are specified LUKS2 default PBKDF values will apply.
If a keyslot is specified (via --key-slot), the passphrase for that
keyslot must be given. If no keyslot is specified and there is still a
free keyslot, then the new parameters will be put into a free keyslot
before the keyslot containing the old parameters is purged. If there is
no free keyslot, then the keyslot with the old parameters is overwritten
directly.
If a keyslot is specified (via --key-slot), the passphrase for that keyslot must be given.
If no keyslot is specified and there is still a free keyslot, then the new parameters will be put into a free keyslot before the keyslot containing the old parameters is purged.
If there is no free keyslot, then the keyslot with the old parameters is overwritten directly.
*WARNING:* If a keyslot is overwritten, a media failure during this
operation can cause the overwrite to fail after the old parameters have
been wiped and make the LUKS container inaccessible.
*WARNING:* If a keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old parameters have been wiped and make the LUKS container inaccessible.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--key-slot, --hash, --header, --disable-locks, --iter-time, --pbkdf,
--pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel,
--keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-slot, --hash, --header, --disable-locks, --iter-time, --pbkdf, --pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --keyslot-cipher, --keyslot-key-size, --timeout, --verify-passphrase].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

33
man/cryptsetup-luksDump.8.adoc
View File

@@ -18,33 +18,22 @@ cryptsetup-luksDump - dump the header information of a LUKS device
Dump the header information of a LUKS device.
If the --dump-volume-key option is used, the LUKS device volume key is
dumped instead of the keyslot info. Together with the --volume-key-file
option, volume key is dumped to a file instead of standard output.
Beware that the volume key cannot be changed without reencryption and
can be used to decrypt the data stored in the LUKS container without a
passphrase and even without the LUKS header. This means that if the
volume key is compromised, the whole device has to be erased or
reencrypted to prevent further access. Use this option carefully.
If the --dump-volume-key option is used, the LUKS device volume key is dumped instead of the keyslot info.
Together with the --volume-key-file option, volume key is dumped to a file instead of standard output.
Beware that the volume key cannot be changed without reencryption and can be used to decrypt the data stored in the LUKS container without a passphrase and even without the LUKS header.
This means that if the volume key is compromised, the whole device has to be erased or reencrypted to prevent further access.
Use this option carefully.
To dump the volume key, a passphrase has to be supplied, either
interactively or via --key-file.
To dump the volume key, a passphrase has to be supplied, either interactively or via --key-file.
To dump unbound key (LUKS2 format only), --unbound parameter, specific
--key-slot id and proper passphrase has to be supplied, either
interactively or via --key-file. Optional --volume-key-file parameter
enables unbound keyslot dump to a file.
To dump unbound key (LUKS2 format only), --unbound parameter, specific --key-slot id and proper passphrase has to be supplied, either interactively or via --key-file.
Optional --volume-key-file parameter enables unbound keyslot dump to a file.
To dump LUKS2 JSON metadata (without basic header information like UUID)
use --dump-json-metadata option.
To dump LUKS2 JSON metadata (without basic header information like UUID) use --dump-json-metadata option.
*<options>* can be [--dump-volume-key, --dump-json-metadata, --key-file,
--keyfile-offset, --keyfile-size, --header, --disable-locks,
--volume-key-file, --type, --unbound, --key-slot, --timeout, --external-tokens-path].
*<options>* can be [--dump-volume-key, --dump-json-metadata, --key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --volume-key-file, --type, --unbound, --key-slot, --timeout, --external-tokens-path].
*WARNING:* If --dump-volume-key is used with --key-file and the argument
to --key-file is '-', no validation question will be asked and no
warning given.
*WARNING:* If --dump-volume-key is used with --key-file and the argument to --key-file is '-', no validation question will be asked and no warning given.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

40
man/cryptsetup-luksFormat.8.adoc
View File

@@ -16,42 +16,24 @@ cryptsetup-luksFormat - initialize a LUKS partition and set the initial passphra
== DESCRIPTION
Initializes a LUKS partition and sets the initial passphrase (for
key-slot 0), either via prompting or via <key file>. Note that if the
second argument is present, then the passphrase is taken from the file
given there, without the need to use the --key-file option. Also note
that for both forms of reading the passphrase from a file you can give
'-' as file name, which results in the passphrase being read from stdin
and the safety-question being skipped.
Initializes a LUKS partition and sets the initial passphrase (for key-slot 0), either via prompting or via <key file>.
Note that if the second argument is present, then the passphrase is taken from the file given there, without the need to use the --key-file option.
Also note that for both forms of reading the passphrase from a file you can give '-' as file name, which results in the passphrase being read from stdin and the safety-question being skipped.
You cannot call luksFormat on a device or filesystem that is mapped or
in use, e.g., mounted filesystem, used in LVM, active RAID member, etc. The
device or filesystem has to be un-mounted in order to call luksFormat.
You cannot call luksFormat on a device or filesystem that is mapped or in use, e.g., mounted filesystem, used in LVM, active RAID member, etc.
The device or filesystem has to be un-mounted in order to call luksFormat.
To use specific version of LUKS format, use _--type luks1_ or _type luks2_.
To use OPAL hardware encryption on a self-encrypting drive, use
_--hw-opal_ or _--hw-opal-only_. Note that some OPAL drives can require
a PSID reset (with deletion of data) before using the LUKS format
with OPAL options.
See _--hw-opal-factory-reset_ option in cryptsetup _erase_ command.
To use OPAL hardware encryption on a self-encrypting drive, use --hw-opal or --hw-opal-only.
Note that some OPAL drives can require a PSID reset (with deletion of data) before using the LUKS format with OPAL options.
See --hw-opal-factory-reset option in cryptsetup _erase_ command.
*<options>* can be [--hash, --cipher, --verify-passphrase, --key-size,
--key-slot, --key-file (takes precedence over optional second argument),
--keyfile-offset, --keyfile-size, --use-random, --use-urandom, --uuid,
--volume-key-file, --iter-time, --header, --pbkdf-force-iterations,
--force-password, --disable-locks, --timeout, --type, --offset,
--align-payload (deprecated)].
*<options>* can be [--hash, --cipher, --verify-passphrase, --key-size, --key-slot, --key-file (takes precedence over optional second argument), --keyfile-offset, --keyfile-size, --use-random, --use-urandom, --uuid, --volume-key-file, --iter-time, --header, --pbkdf-force-iterations, --force-password, --disable-locks, --timeout, --type, --offset, --align-payload (deprecated)].
For LUKS2, additional *<options>* can be [--integrity,
--integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf,
--pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring,
--luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher,
--keyslot-key-size, --integrity-legacy-padding, --hw-opal, --hw-opal-only].
For LUKS2, additional *<options>* can be [--integrity, --integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf, --pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring, --luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher, --keyslot-key-size, --integrity-legacy-padding, --hw-opal, --hw-opal-only].
*WARNING:* Doing a luksFormat on an existing LUKS container will make
all data in the old container permanently irretrievable unless you have a
header backup.
*WARNING:* Doing a luksFormat on an existing LUKS container will make all data in the old container permanently irretrievable unless you have a header backup.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

12
man/cryptsetup-luksHeaderBackup.8.adoc
View File

@@ -22,14 +22,10 @@ Stores a binary backup of the LUKS header and keyslot area. +
*<options>* can be [--header, --header-backup-file, --disable-locks].
*WARNING:* This backup file and a passphrase valid at the time of backup
allows decryption of the LUKS data area, even if the passphrase was
later changed or removed from the LUKS device. Also note that with a
header backup you lose the ability to securely wipe the LUKS device by
just overwriting the header and key-slots. You either need to securely
erase all header backups in addition or overwrite the encrypted data
area as well. The second option is less secure, as some sectors can
survive, e.g., due to defect management.
*WARNING:* This backup file and a passphrase valid at the time of backup allows decryption of the LUKS data area, even if the passphrase was later changed or removed from the LUKS device.
Also note that with a header backup you lose the ability to securely wipe the LUKS device by just overwriting the header and key-slots.
You either need to securely erase all header backups in addition or overwrite the encrypted data area as well.
The second option is less secure, as some sectors can survive, e.g., due to defect management.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

12
man/cryptsetup-luksHeaderRestore.8.adoc
View File

@@ -16,19 +16,15 @@ cryptsetup-luksHeaderRestore - restore a binary backup of the LUKS header and ke
== DESCRIPTION
Restores a binary backup of the LUKS header and keyslot area from the
specified file. +
Restores a binary backup of the LUKS header and keyslot area from the specified file. +
*NOTE:* Using '-' as filename reads the header backup from a file named '-'.
*<options>* can be [--header, --header-backup-file, --disable-locks].
*WARNING:* Header and keyslots will be replaced, only the passphrases
from the backup will work afterward.
*WARNING:* Header and keyslots will be replaced, only the passphrases from the backup will work afterward.
This command requires that the volume key size and data offset of the
LUKS header already on the device and of the header backup match.
Alternatively, if there is no LUKS header on the device, the backup will
also be written to it.
This command requires that the volume key size and data offset of the LUKS header already on the device and of the header backup match.
Alternatively, if there is no LUKS header on the device, the backup will also be written to it.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

24
man/cryptsetup-luksKillSlot.8.adoc
View File

@@ -16,25 +16,17 @@ cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device
== DESCRIPTION
Wipe the key-slot number <key slot> from the LUKS device. Except running
in batch-mode (-q) a remaining passphrase must be supplied, either
interactively or via --key-file. This command can remove the last
remaining key-slot, but requires an interactive confirmation when doing
so. Removing the last passphrase makes a LUKS container permanently
inaccessible.
Wipe the key-slot number <key slot> from the LUKS device.
Except running in batch-mode (-q) a remaining passphrase must be supplied, either interactively or via --key-file.
This command can remove the last remaining key-slot, but requires an interactive confirmation when doing so.
Removing the last passphrase makes a LUKS container permanently inaccessible.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--header, --disable-locks, --type, --verify-passphrase, --timeout].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --verify-passphrase, --timeout].
*WARNING:* If you read the passphrase from stdin (without further
argument or with '-' as an argument to --key-file), batch-mode (-q) will
be implicitly switched on and no warning will be given when you remove
the last remaining passphrase from a LUKS container. Removing the last
passphrase makes the LUKS container permanently inaccessible.
*WARNING:* If you read the passphrase from stdin (without further argument or with '-' as an argument to --key-file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container.
Removing the last passphrase makes the LUKS container permanently inaccessible.
*NOTE:* If there is no passphrase provided (on stdin or through
--key-file argument) and batch-mode (-q) is active, the key-slot is
removed without any other warning.
*NOTE:* If there is no passphrase provided (on stdin or through --key-file argument) and batch-mode (-q) is active, the key-slot is removed without any other warning.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

15
man/cryptsetup-luksRemoveKey.8.adoc
View File

@@ -16,18 +16,13 @@ cryptsetup-luksRemoveKey - remove the supplied passphrase from the LUKS device
== DESCRIPTION
Removes the supplied passphrase from the LUKS device. The passphrase to
be removed can be specified interactively, as the positional argument or
via --key-file.
Removes the supplied passphrase from the LUKS device.
The passphrase to be removed can be specified interactively, as the positional argument or via --key-file.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--header, --disable-locks, --type, --timeout, --verify-passphrase].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --timeout, --verify-passphrase].
*WARNING:* If you read the passphrase from stdin (without further
argument or with '-' as an argument to --key-file), batch-mode (-q) will
be implicitly switched on and no warning will be given when you remove
the last remaining passphrase from a LUKS container. Removing the last
passphrase makes the LUKS container permanently inaccessible.
*WARNING:* If you read the passphrase from stdin (without further argument or with '-' as an argument to --key-file), batch-mode (-q) will be implicitly switched on and no warning will be given when you remove the last remaining passphrase from a LUKS container.
Removing the last passphrase makes the LUKS container permanently inaccessible.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

11
man/cryptsetup-luksResume.8.adoc
View File

@@ -16,15 +16,10 @@ cryptsetup-luksResume - resume a suspended device and reinstate the key
== DESCRIPTION
Resumes a suspended device and reinstates the encryption key. Prompts
interactively for a passphrase if no token is usable (LUKS2 only) or
--key-file is not given.
Resumes a suspended device and reinstates the encryption key.
Prompts interactively for a passphrase if no token is usable (LUKS2 only) or --key-file is not given.
*<options>* can be [--key-file, --keyfile-size, --keyfile-offset,
--key-slot, --header, --disable-keyring, --disable-locks, --token-id,
--token-only, --token-type, --disable-external-tokens, --type, --tries,
--timeout, --verify-passphrase, --volume-key-keyring, --link-vk-to-keyring,
--external-tokens-path].
*<options>* can be [--key-file, --keyfile-size, --keyfile-offset, --key-slot, --header, --disable-keyring, --disable-locks, --token-id, --token-only, --token-type, --disable-external-tokens, --type, --tries, --timeout, --verify-passphrase, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

16
man/cryptsetup-luksSuspend.8.adoc
View File

@@ -16,22 +16,16 @@ cryptsetup-luksSuspend - suspends an active device and wipes the key
== DESCRIPTION
Suspends an active device (all IO operations will block and accesses to
the device will wait indefinitely) and wipes the encryption key from
kernel memory. Needs kernel 2.6.19 or later.
Suspends an active device (all IO operations will block and accesses to the device will wait indefinitely) and wipes the encryption key from kernel memory.
Needs kernel 2.6.19 or later.
While the _luksSuspend_ operation wipes encryption keys from memory,
it does not remove possible plaintext data in various caches or in-kernel
metadata for mounted filesystems.
While the _luksSuspend_ operation wipes encryption keys from memory, it does not remove possible plaintext data in various caches or in-kernel metadata for mounted filesystems.
After this operation, you have to use _luksResume_ to reinstate the
encryption key and unblock the device or _close_ to remove the mapped
device.
After this operation, you have to use _luksResume_ to reinstate the encryption key and unblock the device or _close_ to remove the mapped device.
*<options>* can be [--header, --disable-locks].
*WARNING:* Never suspend the device on which the cryptsetup binary
resides.
*WARNING:* Never suspend the device on which the cryptsetup binary resides.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

123
man/cryptsetup-open.8.adoc
View File

@@ -17,8 +17,7 @@ cryptsetup-open, cryptsetup-create, cryptsetup-plainOpen, cryptsetup-luksOpen, c
== DESCRIPTION
Opens (creates a mapping with) <name> backed by device <device>.
Device type can be _plain_, _luks_ (default), _luks1_, _luks2_,
_loopaes_ or _tcrypt_.
Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, _loopaes_ or _tcrypt_.
For backward compatibility there are *open* command aliases:
@@ -29,10 +28,8 @@ For backward compatibility there are *open* command aliases:
*tcryptOpen*: open --type tcrypt +
*bitlkOpen*: open --type bitlk
*<options>* are type specific and are described below for individual
device types. For *create*, the order of the <name> and <device> options
is inverted for historical reasons, all other aliases use the standard
*<device> <name>* order.
*<options>* are type specific and are described below for individual device types.
For *create*, the order of the <name> and <device> options is inverted for historical reasons, all other aliases use the standard *<device> <name>* order.
=== PLAIN
*open --type plain <device> <name>* --cipher <spec> --key-size <bits> --hash <alg> +
@@ -41,32 +38,24 @@ create <name> <device> (OBSOLETE syntax)
Opens (creates a mapping with) <name> backed by device <device>.
*WARNING:* You should always specify options --cipher, --key-size and
(if no keyfile or keyring is used) then also --hash to avoid incompatibility as
default values can be different in older cryptsetup versions. +
*WARNING:* You should always specify options --cipher, --key-size and (if no keyfile or keyring is used) then also --hash to avoid incompatibility as default values can be different in older cryptsetup versions. +
The plain format also allows retrieving a volume key from a kernel keyring
specified by --volume-key-keyring. Key in kernel keyring must be configured
before issuing cryptsetup commands, as cryptsetup does not upload any keys to
the keyring in plain mode. For subsequent commands (like resize), the user must
ensure that the key in the keyring is unchanged. Otherwise, reloading the key
can cause data corruption after an unexpected key change.
The plain format also allows retrieving a volume key from a kernel keyring specified by --volume-key-keyring.
Key in kernel keyring must be configured before issuing cryptsetup commands, as cryptsetup does not upload any keys to the keyring in plain mode.
For subsequent commands (like resize), the user must ensure that the key in the keyring is unchanged.
Otherwise, reloading the key can cause data corruption after an unexpected key change.
*<options>* can be [--hash, --cipher, --sector-size,
--key-file, --keyfile-size, --keyfile-offset, --key-size, --offset,
--skip, --device-size, --size, --readonly, --shared, --allow-discards,
--refresh, --timeout, --verify-passphrase, --iv-large-sectors, --volume-key-keyring].
*<options>* can be [--hash, --cipher, --sector-size, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --device-size, --size, --readonly, --shared, --allow-discards, --refresh, --timeout, --verify-passphrase, --iv-large-sectors, --volume-key-keyring].
*EXAMPLES:*
To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, you can use
To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, you can use:
*cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1*
The decrypted device can then be used as a normal block device to mount a filesystem.
To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify
keyring with the key and remove hash specification, for example, to use *%trusted:mykey*:
To map a device with a volume key in the preconfigured trusted or encrypted keyring, you need to specify keyring with the key and remove hash specification, for example, to use *%trusted:mykey*:
*cryptsetup open --type plain /dev/sda10 e1 --volume-key-keyring=%trusted:mykey --cipher aes-xts-plain64 --key-size 256*
@@ -77,26 +66,15 @@ Note that the key size must match the preconfigured key in the keyring.
open --type <luks1|luks2> <device> <name> (explicit version request) +
luksOpen <device> <name> (old syntax)
Opens the LUKS device <device> and sets up a mapping <name> after
successful verification of the supplied passphrase.
Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase.
First, the passphrase is searched in LUKS2 tokens unprotected by PIN.
If such token does not exist (or fails to unlock keyslot) and
also the passphrase is not supplied via --key-file, the command
prompts for passphrase interactively.
If such token does not exist (or fails to unlock keyslot) and also the passphrase is not supplied via --key-file, the command prompts for passphrase interactively.
If there is valid LUKS2 token but it requires PIN to unlock assigned keyslot,
it is not used unless one of following options is added: --token-only,
--token-type where type matches desired PIN protected token or --token-id with id
matching PIN protected token.
If there is valid LUKS2 token but it requires PIN to unlock assigned keyslot, it is not used unless one of following options is added: --token-only,
--token-type where type matches desired PIN protected token or --token-id with id matching PIN protected token.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
--readonly, --test-passphrase, --allow-discards, --header, --key-slot,
--volume-key-file, --token-id, --token-only, --token-type,
--disable-external-tokens, --disable-keyring, --disable-locks, --type,
--refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout,
--verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring,
--external-tokens-path].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --readonly, --test-passphrase, --allow-discards, --header, --key-slot, --volume-key-file, --token-id, --token-only, --token-type, --disable-external-tokens, --disable-keyring, --disable-locks, --type, --refresh, --serialize-memory-hard-pbkdf, --unbound, --tries, --timeout, --verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring, --external-tokens-path].
=== loopAES
*open --type loopaes <device> <name> --key-file <keyfile>* +
@@ -104,31 +82,25 @@ loopaesOpen <device> <name> --key-file <keyfile> (old syntax)
Opens the loop-AES <device> and sets up a mapping <name>.
If the key file is encrypted with GnuPG, then you have to use
--key-file=- and decrypt it before use, e.g., like this: +
If the key file is encrypted with GnuPG, then you have to use --key-file=- and decrypt it before use, e.g., like this: +
gpg --decrypt <keyfile> | cryptsetup loopaesOpen --key-file=- <device>
<name>
*WARNING:* The loop-AES extension cannot use the direct input of the key
file on the real terminal because the keys are separated by end-of-line and
only part of the multi-key file would be read. +
*WARNING:* The loop-AES extension cannot use the direct input of the key file on the real terminal because the keys are separated by end-of-line and only part of the multi-key file would be read. +
If you need it in script, just use the pipe redirection: +
echo $keyfile | cryptsetup loopaesOpen --key-file=- <device> <name>
Use --keyfile-size to specify the proper key length if needed.
Use --offset to specify device offset. Note that the units need to be
specified in number of 512 byte sectors.
Use --offset to specify device offset.
Note that the units need to be specified in number of 512 byte sectors.
Use --skip to specify the IV offset. If the original device used an
offset and but did not use it in IV sector calculations, you have to
explicitly use --skip 0 in addition to the offset parameter.
Use --skip to specify the IV offset.
If the original device used an offset and but did not use it in IV sector calculations, you have to explicitly use --skip 0 in addition to the offset parameter.
Use --hash to override the default hash function for passphrase
hashing (otherwise it is detected according to key size).
Use --hash to override the default hash function for passphrase hashing (otherwise it is detected according to key size).
*<options>* can be [--cipher, --key-file, --keyfile-size, --keyfile-offset,
--key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh].
*<options>* can be [--cipher, --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset, --skip, --hash, --readonly, --allow-discards, --refresh].
=== TrueCrypt and VeraCrypt
*open --type tcrypt <device> <name>* +
@@ -137,56 +109,37 @@ tcryptOpen <device> <name> (old syntax)
Opens the TCRYPT (TrueCrypt and VeraCrypt compatible) <device> and sets
up a mapping <name>.
*<options>* can be [--key-file, --tcrypt-hidden, --tcrypt-system,
--tcrypt-backup, --readonly, --test-passphrase, --allow-discards,
--veracrypt (ignored), --disable-veracrypt, --veracrypt-pim,
--veracrypt-query-pim, --header,
--cipher, --hash, --tries, --timeout, --verify-passphrase].
*<options>* can be [--key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --readonly, --test-passphrase, --allow-discards, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --header, --cipher, --hash, --tries, --timeout, --verify-passphrase].
The keyfile parameter allows a combination of file content with the
passphrase and can be repeated. Note that using keyfiles is compatible
with TCRYPT and is different from LUKS keyfile logic.
The keyfile parameter allows a combination of file content with the passphrase and can be repeated.
Note that using keyfiles is compatible with TCRYPT and is different from LUKS keyfile logic.
If --cipher or --hash options are used, only cipher chains or PBKDF2
variants with the specified hash algorithms are checked. This could
speed up unlocking the device (but also it reveals some information
about the container).
If --cipher or --hash options are used, only cipher chains or PBKDF2 variants with the specified hash algorithms are checked.
This could speed up unlocking the device (but also it reveals some information about the container).
If you use --header in combination with hidden or system options, the
header file must contain specific headers on the same positions as the
original encrypted container.
If you use --header in combination with hidden or system options, the header file must contain specific headers on the same positions as the original encrypted container.
*WARNING:* Option --allow-discards cannot be combined with option
--tcrypt-hidden. For normal mapping, it can cause the destruction of
hidden volume (hidden volume appears as unused space for outer volume
so this space can be discarded).
*WARNING:* Option --allow-discards cannot be combined with option --tcrypt-hidden.
For normal mapping, it can cause the destruction of hidden volume (hidden volume appears as unused space for outer volume so this space can be discarded).
=== BitLocker
*open --type bitlk <device> <name>* +
bitlkOpen <device> <name> (old syntax)
Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
<name>.
Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping <name>.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size,
--readonly, --test-passphrase, --allow-discards --volume-key-file, --tries,
--timeout, --verify-passphrase].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase].
Note that --test-passphrase doesn't work with --volume-key-file because
we cannot check whether the provided volume key is correct for this device
or not. When using --volume-key-file the device will be opened even if
the provided key is not correct.
Note that --test-passphrase doesn't work with --volume-key-file because we cannot check whether the provided volume key is correct for this device or not.
When using --volume-key-file the device will be opened even if the provided key is not correct.
=== FileVault2
*open --type fvault2 <device> <name>* +
fvault2Open <device> <name> (old syntax)
Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a mapping
<name>.
Opens the FVAULT2 (a FileVault2 compatible) <device> and sets up a mapping <name>.
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size,
--readonly, --test-passphrase, --allow-discards --volume-key-file, --tries,
--timeout, --verify-passphrase].
*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --key-size, --readonly, --test-passphrase, --allow-discards --volume-key-file, --tries, --timeout, --verify-passphrase].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

77
man/cryptsetup-reencrypt.8.adoc
View File

@@ -26,28 +26,20 @@ There are 3 basic modes of operation:
<device> or --active-name <name> (LUKS2 only) is mandatory parameter.
Cryptsetup _reencrypt_ action can be used to change reencryption parameters
which otherwise require full on-disk data change (re-encryption). The
_reencrypt_ action reencrypts data on LUKS device in-place.
Cryptsetup _reencrypt_ action can be used to change reencryption parameters which otherwise require full on-disk data change (re-encryption).
The _reencrypt_ action reencrypts data on LUKS device in-place.
You can regenerate *volume key* (the real key used in on-disk encryption
unlocked by passphrase), *cipher*, *cipher mode* or *encryption sector size*
(LUKS2 only).
You can regenerate *volume key* (the real key used in on-disk encryption unlocked by passphrase), *cipher*, *cipher mode* or *encryption sector size* (LUKS2 only).
*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g. to recover
from a leak) you need to use them in that order to not leak the new volume key.
*WARNING:* If you need to use both luksChangeKey and reencrypt (e.g. to recover from a leak) you need to use them in that order to not leak the new volume key.
Reencryption process may be safely interrupted by a user via SIGINT
signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd
during system shutdown).
Reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c).
Same applies to SIGTERM signal (i.e. issued by systemd during system shutdown).
For in-place encryption mode, the _reencrypt_ action additionally takes all
options available for _luksFormat_ action for respective LUKS version (see
cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8).
For in-place encryption mode, the _reencrypt_ action additionally takes all options available for _luksFormat_ action for respective LUKS version (see cryptsetup-luksFormat man page for more details).
See *cryptsetup-luksFormat*(8).
*NOTE* that for encrypt and decrypt mode, the whole device must be
treated as unencrypted -- there are no guarantees of confidentiality as
part of the device contains plaintext.
*NOTE* that for encrypt and decrypt mode, the whole device must be treated as unencrypted -- there are no guarantees of confidentiality as part of the device contains plaintext.
*ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.*
@@ -97,55 +89,40 @@ part of the device contains plaintext.
== LUKS2 REENCRYPTION
With <device> parameter cryptsetup looks up active <device> dm mapping.
If no active mapping is detected, it starts offline LUKS2 reencryption
otherwise online reencryption takes place.
If no active mapping is detected, it starts offline LUKS2 reencryption otherwise online reencryption takes place.
To resume already initialized or interrupted reencryption, just run the
cryptsetup _reencrypt_ command again to continue the reencryption
operation. Reencryption may be resumed with different --resilience or
--hotzone-size unless implicit datashift resilience mode is used: either
encrypt mode with --reduce-device-size option or decrypt mode with
original LUKS2 header exported in --header file.
To resume already initialized or interrupted reencryption, just run the cryptsetup _reencrypt_ command again to continue the reencryption operation.
Reencryption may be resumed with different --resilience or --hotzone-size unless implicit datashift resilience mode is used: either encrypt mode with --reduce-device-size option or decrypt mode with original LUKS2 header exported in --header file.
If the reencryption process was interrupted abruptly (reencryption
process crash, system crash, poweroff) it may require recovery. The
recovery is currently run automatically on next activation (action
_open_) when needed or explicitly by user (action _repair_).
If the reencryption process was interrupted abruptly (reencryption process crash, system crash, poweroff) it may require recovery.
The recovery is currently run automatically on next activation (action _open_) when needed or explicitly by user (action _repair_).
Optional parameter <new_name> takes effect only with encrypt option
and it activates device <new_name> immediately after encryption
initialization gets finished. That's useful when device needs to be
ready as soon as possible and mounted (used) before full data area
encryption is completed.
Optional parameter <new_name> takes effect only with encrypt option and it activates device <new_name> immediately after encryption initialization gets finished.
That's useful when device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed.
== LUKS1 REENCRYPTION
Current working directory must be writable and temporary files created during
reencryption must be present. During reencryption process the LUKS1 device is
marked unavailable and must be offline (no dm-crypt mapping or mounted
filesystem).
Current working directory must be writable and temporary files created during reencryption must be present.
During reencryption process the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem).
*WARNING*: The LUKS1 reencryption code is not resistant to hardware
or kernel failures during reencryption (you can lose your data in this case).
*WARNING*: The LUKS1 reencryption code is not resistant to hardware or kernel failures during reencryption (you can lose your data in this case).
include::man/common_options.adoc[]
== EXAMPLES
*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is
default.
*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is default.
=== LUKS2 ENCRYPTION EXAMPLES
Encrypt LUKS2 device (in-place). Make sure last 32 MiB on _/dev/plaintext_
is unused (e.g.: does not contain filesystem data):
Encrypt LUKS2 device (in-place).
Make sure last 32 MiB on _/dev/plaintext_ is unused (e.g.: does not contain filesystem data):
*cryptsetup reencrypt --encrypt --type luks2 --reduce-device-size 32m /dev/plaintext_device*
Encrypt LUKS2 device (in-place). Only the initial 1 GiB of original
_/dev/plaintext_ data is encrypted while being shifted backwards.
Make sure last 32 MiB (tail) on the data device is unused (e.g.: does
not contain any data):
Encrypt LUKS2 device (in-place).
Only the initial 1 GiB of original _/dev/plaintext_ data is encrypted while being shifted backwards.
Make sure last 32 MiB (tail) on the data device is unused (e.g.: does not contain any data):
*cryptsetup reencrypt --encrypt --type luks2 --device-size 1g --reduce-device-size 32m /dev/plaintext_device*
@@ -173,8 +150,8 @@ All other keyslots will be removed after the reencryption finishes.
*cryptsetup reencrypt --token-id 3 /dev/encrypted_device*
Reencrypt LUKS2 device using keyslots associated to all 'systemd-tpm2'
tokens. All other keyslots will be removed after the reencryption finishes.
Reencrypt LUKS2 device using keyslots associated to all 'systemd-tpm2' tokens.
All other keyslots will be removed after the reencryption finishes.
*cryptsetup reencrypt --token-type systemd-tpm2 /dev/encrypted_device*

30
man/cryptsetup-refresh.8.adoc
View File

@@ -18,36 +18,24 @@ cryptsetup-refresh - refresh parameters of an active mapping
Refreshes parameters of active mapping <name>.
Updates parameters of active device <name> without the need to deactivate
the device (and umount filesystem). Currently, it supports parameters
refresh on following devices: LUKS1, LUKS2 (including authenticated
encryption), plain crypt and loop-AES.
Updates parameters of active device <name> without the need to deactivate the device (and umount filesystem).
Currently, it supports parameters refresh on following devices: LUKS1, LUKS2 (including authenticated encryption), plain crypt and loop-AES.
Mandatory parameters are identical to those of an open action for
the respective device type.
Mandatory parameters are identical to those of an open action for the respective device type.
You may change following parameters on all devices
--perf-same_cpu_crypt, --perf-submit_from_crypt_cpus,
--perf-no_read_workqueue, --perf-no_write_workqueue and
--allow-discards.
You may change following parameters on all devices --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue and --allow-discards.
Refreshing the device without any optional parameter will refresh the device
with default setting (respective to device type).
Refreshing the device without any optional parameter will refresh the device with default setting (respective to device type).
*LUKS2 only:*
The --integrity-no-journal parameter affects only LUKS2 devices with
the underlying dm-integrity device.
The --integrity-no-journal parameter affects only LUKS2 devices with the underlying dm-integrity device.
Adding option --persistent stores any combination of device parameters
above in LUKS2 metadata (only after successful refresh operation).
Adding option --persistent stores any combination of device parameters above in LUKS2 metadata (only after successful refresh operation).
The --disable-keyring parameter refreshes a device with volume key passed in
dm-crypt driver.
The --disable-keyring parameter refreshes a device with volume key passed in dm-crypt driver.
*<options>* can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus,
--perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring,
--disable-locks, --persistent, --integrity-no-journal].
*<options>* can be [--allow-discards, --perf-same_cpu_crypt, --perf-submit_from_crypt_cpus, --perf-no_read_workqueue, --perf-no_write_workqueue, --header, --disable-keyring, --disable-locks, --persistent, --integrity-no-journal].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

48
man/cryptsetup-repair.8.adoc
View File

@@ -16,47 +16,37 @@ cryptsetup-repair - repair the device metadata
== DESCRIPTION
Tries to repair the device metadata if possible. Currently supported
only for LUKS device type.
Tries to repair the device metadata if possible.
Currently supported only for LUKS device type.
This command is useful to fix some known benign LUKS metadata header
corruptions. Only basic corruptions of unused keyslot are fixable. This
command will only change the LUKS header, not any key-slot data. You may
enforce LUKS version by adding --type option.
This command is useful to fix some known benign LUKS metadata header corruptions.
Only basic corruptions of unused keyslot are fixable.
This command will only change the LUKS header, not any key-slot data.
You may enforce LUKS version by adding --type option.
It also repairs (upgrades) LUKS2 reencryption metadata by adding
a metadata digest that protects it against malicious changes.
It also repairs (upgrades) LUKS2 reencryption metadata by adding a metadata digest that protects it against malicious changes.
If LUKS2 reencryption was interrupted in the middle of writing
reencryption segment the repair command can be used to perform
reencryption recovery so that reencryption can continue later.
Repairing reencryption requires verification of reencryption
keyslot so passphrase or keyfile is needed.
If LUKS2 reencryption was interrupted in the middle of writing reencryption segment the repair command can be used to perform reencryption recovery so that reencryption can continue later.
Repairing reencryption requires verification of reencryption keyslot so passphrase or keyfile is needed.
=== LUKS keyslots corruption detection
The repair command also checks for detectable corruption of keyslot
content. Corruption of a keyslot results in a situation when a known
password is no longer accepted. It can happen due to storage media
failure or overwriting the keyslot area by some other data.
Only certain corruptions, usually only a low-entropy area
(like zeroed blocks), can be detected.
The repair command also checks for detectable corruption of keyslot content.
Corruption of a keyslot results in a situation when a known password is no longer accepted.
It can happen due to storage media failure or overwriting the keyslot area by some other data.
Only certain corruptions, usually only a low-entropy area (like zeroed blocks), can be detected.
The detection prints only warnings. It does not modify keyslots.
It can also print more specific offsets on the device for detailed
manual inspection.
The detection prints only warnings.
It does not modify keyslots.
It can also print more specific offsets on the device for detailed manual inspection.
Please note that the warning can be a false positive
(no real corruption happened).
Please note that the warning can be a false positive (no real corruption happened).
Conversely, if the keyslot is corrupted, no recovery is possible.
You have to use LUKS header backup.
*<options>* can be [--timeout, --verify-passphrase, --disable-locks, --type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot].
*<options>* can be [--timeout, --verify-passphrase, --disable-locks,
--type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot].
*WARNING:* Always create a binary backup of the original header before
calling this command.
*WARNING:* Always create a binary backup of the original header before calling this command.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

24
man/cryptsetup-resize.8.adoc
View File

@@ -18,25 +18,17 @@ cryptsetup-resize - resize an active mapping
Resizes an active mapping <name>.
If --size (in 512-bytes sectors) or --device-size are not specified, the
size is computed from the underlying device. For LUKS it is the size of
the underlying device without the area reserved for LUKS header (see
data payload offset in *luksDump* command). For plain crypt device, the
whole device size is used.
If --size (in 512-bytes sectors) or --device-size are not specified, the size is computed from the underlying device.
For LUKS it is the size of the underlying device without the area reserved for LUKS header (see data payload offset in *luksDump* command).
For plain crypt device, the whole device size is used.
Note that this does not change the raw device geometry, it just changes
how many sectors of the raw device are represented in the mapped device.
Note that this does not change the raw device geometry, it just changes how many sectors of the raw device are represented in the mapped device.
If cryptsetup detected volume key for active device loaded in kernel
keyring service, resize action would first try to retrieve the key using
a token. Only if it failed, it'd ask for a passphrase to unlock a
keyslot (LUKS) or to derive a volume key again (plain mode). The kernel
keyring is used by default for LUKS2 devices.
If cryptsetup detected volume key for active device loaded in kernel keyring service, resize action would first try to retrieve the key using a token.
Only if it failed, it'd ask for a passphrase to unlock a keyslot (LUKS) or to derive a volume key again (plain mode).
The kernel keyring is used by default for LUKS2 devices.
*<options>* can be [--size, --device-size, --token-id, --token-only,
--token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset,
--timeout, --disable-external-tokens, --disable-locks, --disable-keyring,
--volume-key-keyring, --verify-passphrase, --timeout, --external-tokens-path].
*<options>* can be [--size, --device-size, --token-id, --token-only, --token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset, --timeout, --disable-external-tokens, --disable-locks, --disable-keyring, --volume-key-keyring, --verify-passphrase, --timeout, --external-tokens-path].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

24
man/cryptsetup-ssh.8.adoc
View File

@@ -14,12 +14,10 @@ cryptsetup-ssh - manage LUKS2 SSH token
== DESCRIPTION
Experimental cryptsetup plugin for unlocking LUKS2 devices with token
connected to an SSH server.
Experimental cryptsetup plugin for unlocking LUKS2 devices with token connected to an SSH server.
This plugin currently allows only adding a token to an existing key
slot. See *cryptsetup(8)* for instructions on how to remove, import or
export the token.
This plugin currently allows only adding a token to an existing key slot.
See *cryptsetup(8)* for instructions on how to remove, import or export the token.
=== Add operation
@@ -27,13 +25,10 @@ export the token.
Adds the SSH token to *<device>*.
The specified SSH server must contain a key file on the specified path with
a passphrase for an existing key slot on the device. Provided
credentials will be used by cryptsetup to get the password when opening
the device using the token.
The specified SSH server must contain a key file on the specified path with a passphrase for an existing key slot on the device.
Provided credentials will be used by cryptsetup to get the password when opening the device using the token.
Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are
required for this operation.
Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are required for this operation.
== OPTIONS
@@ -47,8 +42,8 @@ Show debug messages including JSON metadata
Show help
*--key-slot* _number_::
Keyslot to assign the token to. If not specified, the token will be
assigned to the first key slot matching provided passphrase.
Keyslot to assign the token to.
If not specified, the token will be assigned to the first key slot matching provided passphrase.
*--ssh-keypath* _string_::
Path to the SSH key for connecting to the remote server.
@@ -70,8 +65,7 @@ Print program version
== NOTES
The information provided when adding the token (SSH server address, user
and paths) will be stored in the LUKS2 header in plaintext.
The information provided when adding the token (SSH server address, user and paths) will be stored in the LUKS2 header in plaintext.
== AUTHORS

18
man/cryptsetup-tcryptDump.8.adoc
View File

@@ -18,20 +18,14 @@ cryptsetup-tcryptDump - dump the header information of a TCRYPT (TrueCrypt or Ve
Dump the header information of a TCRYPT (TrueCrypt or VeraCrypt compatible) device.
If the --dump-volume-key option is used, the TCRYPT device volume key is
dumped instead of TCRYPT header info. Beware that the volume key (or
concatenated volume keys if cipher chain is used) can be used to decrypt
the data stored in the TCRYPT container without a passphrase. This means
that if the volume key is compromised, the whole device has to be erased
to prevent further access. Use this option carefully.
If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of TCRYPT header info.
Beware that the volume key (or concatenated volume keys if cipher chain is used) can be used to decrypt the data stored in the TCRYPT container without a passphrase.
This means that if the volume key is compromised, the whole device has to be erased to prevent further access.
Use this option carefully.
*<options>* can be [--dump-volume-key, --key-file, --tcrypt-hidden,
--tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt,
--veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header,
--verify-passphrase, --timeout].
*<options>* can be [--dump-volume-key, --key-file, --tcrypt-hidden, --tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt, --veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header, --verify-passphrase, --timeout].
The keyfile parameter allows a combination of file content with the
passphrase and can be repeated.
The keyfile parameter allows a combination of file content with the passphrase and can be repeated.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

40
man/cryptsetup-token.8.adoc
View File

@@ -16,40 +16,30 @@ cryptsetup-token - manage LUKS2 tokens
== DESCRIPTION
Action _add_ creates a new keyring token to enable auto-activation of the
device. For the auto-activation, the passphrase must be stored in
keyring with the specified description. Usually, the passphrase should
be stored in _user_ or _user-session_ keyring. The _token_ command is
supported only for LUKS2.
Action _add_ creates a new keyring token to enable auto-activation of the device.
For the auto-activation, the passphrase must be stored in keyring with the specified description.
Usually, the passphrase should be stored in _user_ or _user-session_ keyring.
The _token_ command is supported only for LUKS2.
For adding new keyring token, option --key-description is mandatory.
Also, new token is assigned to key slot specified with --key-slot option
or to all active key slots in the case --key-slot option is omitted.
Also, new token is assigned to key slot specified with --key-slot option or to all active key slots in the case --key-slot option is omitted.
To remove existing token, specify the token ID which should be removed
with --token-id option.
To remove existing token, specify the token ID which should be removed with --token-id option.
*WARNING:* The action _token remove_ removes any token type, not just
_keyring_ type from token slot specified by --token-id option.
*WARNING:* The action _token remove_ removes any token type, not just _keyring_ type from token slot specified by --token-id option.
Action _import_ can store arbitrary valid token json in LUKS2 header. It
may be passed via standard input or via file passed in --json-file
option. If you specify --key-slot then successfully imported token is
also assigned to the key slot.
Action _import_ can store arbitrary valid token json in LUKS2 header.
It may be passed via standard input or via file passed in --json-file option.
If you specify --key-slot then successfully imported token is also assigned to the key slot.
Action _export_ writes requested token JSON to a file passed with
--json-file or to standard output.
Action _export_ writes requested token JSON to a file passed with --json-file or to standard output.
Action _unassign_ removes token binding to specified keyslot. Both token
and keyslot must be specified by --token-id and --key-slot parameters.
Action _unassign_ removes token binding to specified keyslot.
Both token and keyslot must be specified by --token-id and --key-slot parameters.
If --token-id is used with action _add_ or action _import_ and a token
with that ID already exists, option --token-replace can be used to
replace the existing token.
If --token-id is used with action _add_ or action _import_ and a token with that ID already exists, option --token-replace can be used to replace the existing token.
*<options>* can be [--header, --token-id, --key-slot, --key-description,
--disable-external-tokens, --disable-locks, --disable-keyring,
--json-file, --token-replace, --unbound, --external-tokens-path].
*<options>* can be [--header, --token-id, --key-slot, --key-description, --disable-external-tokens, --disable-locks, --disable-keyring, --json-file, --token-replace, --unbound, --external tokens-path].
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

557
man/cryptsetup.8.adoc
View File

@@ -14,19 +14,14 @@ cryptsetup - manage plain dm-crypt, LUKS, and other encrypted volumes
== DESCRIPTION
cryptsetup is used to conveniently setup dm-crypt managed device-mapper
mappings. These include plain dm-crypt volumes and LUKS volumes. The
difference is that LUKS uses a metadata header and can hence offer more
features than plain dm-crypt. On the other hand, the header is visible
and vulnerable to damage.
cryptsetup is used to conveniently setup dm-crypt managed device-mapper mappings.
These include plain dm-crypt volumes and LUKS volumes.
The difference is that LUKS uses a metadata header and can hence offer more features than plain dm-crypt.
On the other hand, the header is visible and vulnerable to damage.
In addition, cryptsetup provides limited support for the use of loop-AES
volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes,
and for hardware-based encryption on OPAL capable drives.
In addition, cryptsetup provides limited support for the use of loop-AES volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes, and for hardware-based encryption on OPAL capable drives.
For more information about specific cryptsetup action see
*cryptsetup-<action>*(8), where *<action>* is the name of the
cryptsetup action.
For more information about specific cryptsetup action see *cryptsetup-<action>*(8), where *<action>* is the name of the cryptsetup action.
== BASIC ACTIONS
@@ -70,12 +65,11 @@ See *cryptsetup-reencrypt*(8).
== PLAIN MODE
Plain dm-crypt encrypts the device sector-by-sector with a single,
non-salted hash of the passphrase. No checks are performed, no metadata
is used. There is no formatting operation. When the raw device is mapped
(opened), the usual device operations can be used on the mapped device,
including filesystem creation. Mapped devices usually reside in
/dev/mapper/<name>.
Plain dm-crypt encrypts the device sector-by-sector with a single, non-salted hash of the passphrase.
No checks are performed, no metadata is used.
There is no formatting operation.
When the raw device is mapped (opened), the usual device operations can be used on the mapped device, including filesystem creation.
Mapped devices usually reside in /dev/mapper/<name>.
The following are valid plain device type actions:
@@ -88,39 +82,27 @@ See *cryptsetup-open*(8).
== LUKS EXTENSION
LUKS, the Linux Unified Key Setup, is a standard for disk encryption. It
adds a standardized header at the start of the device, a key-slot area
directly behind the header and the bulk data area behind that. The whole
set is called a 'LUKS container'. The device that a LUKS container
resides on is called a 'LUKS device'. For most purposes, both terms can
be used interchangeably. But note that when the LUKS header is at a
nonzero offset in a device, then the device is not a LUKS device
anymore, but has a LUKS container stored in it at an offset.
LUKS, the Linux Unified Key Setup, is a standard for disk encryption.
It adds a standardized header at the start of the device, a key-slot area directly behind the header and the bulk data area behind that.
The whole set is called a 'LUKS container'.
The device that a LUKS container resides on is called a 'LUKS device'.
For most purposes, both terms can be used interchangeably.
But note that when the LUKS header is at a nonzero offset in a device, then the device is not a LUKS device anymore, but has a LUKS container stored in it at an offset.
LUKS can manage multiple passphrases that can be individually revoked or
changed and that can be securely scrubbed from persistent media due to
the use of anti-forensic stripes. Passphrases are protected against
brute-force and dictionary attacks by Password-Based Key Derivation
Function (PBKDF).
LUKS can manage multiple passphrases that can be individually revoked or changed and that can be securely scrubbed from persistent media due to the use of anti-forensic stripes.
Passphrases are protected against brute-force and dictionary attacks by Password-Based Key Derivation Function (PBKDF).
LUKS2 is a new version of header format that allows additional
extensions like different PBKDF algorithm or authenticated encryption.
You can format device with LUKS2 header if you specify *--type luks2* in
*luksFormat* command. For activation, the format is already recognized
automatically.
LUKS2 is a new version of header format that allows additional extensions like different PBKDF algorithm or authenticated encryption.
You can format device with LUKS2 header if you specify *--type luks2* in *luksFormat* command.
For activation, the format is already recognized automatically.
Each passphrase, also called a *key* in this document, is associated
with one of 8 key-slots. Key operations that do not specify a slot
affect the first slot that matches the supplied passphrase or the first
empty slot if a new passphrase is added.
Each passphrase, also called a *key* in this document, is associated with one of 8 key-slots.
Key operations that do not specify a slot affect the first slot that matches the supplied passphrase or the first empty slot if a new passphrase is added.
The *<device>* parameter can also be specified by a LUKS UUID in the
format UUID=<uuid>. Translation to real device name uses symlinks in
/dev/disk/by-uuid directory.
The *<device>* parameter can also be specified by a LUKS UUID in the format UUID=<uuid>.
Translation to real device name uses symlinks in /dev/disk/by-uuid directory.
To specify a detached header, the *--header* parameter can be used in
all LUKS commands and always takes precedence over the positional
*<device>* parameter.
To specify a detached header, the *--header* parameter can be used in all LUKS commands and always takes precedence over the positional *<device>* parameter.
The following are valid LUKS actions:
@@ -134,16 +116,13 @@ See *cryptsetup-luksFormat*(8).
*open --type luks <device> <name>* +
luksOpen <device> <name> (*old syntax*)
Opens the LUKS device <device> and sets up a mapping <name> after
successful verification of the supplied passphrase. +
Opens the LUKS device <device> and sets up a mapping <name> after successful verification of the supplied passphrase. +
See *cryptsetup-open*(8).
=== SUSPEND
*luksSuspend <name>*
Suspends an active device (all IO operations will block and accesses to
the device will wait indefinitely) and wipes the encryption key from
kernel memory. +
Suspends an active device (all IO operations will block and accesses to the device will wait indefinitely) and wipes the encryption key from kernel memory. +
See *cryptsetup-luksSuspend*(8).
=== RESUME
@@ -216,8 +195,7 @@ See *cryptsetup-luksHeaderBackup*(8).
=== HEADER RESTORE
*luksHeaderRestore <device> --header-backup-file <file>*
Restores a binary backup of the LUKS header and keyslot area from the
specified file. +
Restores a binary backup of the LUKS header and keyslot area from the specified file. +
See *cryptsetup-luksHeaderRestore*(8).
=== TOKEN
@@ -240,8 +218,7 @@ See *cryptsetup-config*(8).
== loop-AES EXTENSION
cryptsetup supports mapping loop-AES encrypted partition using a
compatibility mode.
Cryptsetup supports mapping loop-AES encrypted partition using a compatibility mode.
=== OPEN
*open --type loopaes <device> <name> --key-file <keyfile>* +
@@ -250,74 +227,48 @@ loopaesOpen <device> <name> --key-file <keyfile> (*old syntax*)
Opens the loop-AES <device> and sets up a mapping <name>. +
See *cryptsetup-open*(8).
See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES]
for more information regarding loop-AES.
See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES] for more information regarding loop-AES.
== TCRYPT (TrueCrypt and VeraCrypt compatible) EXTENSION
cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted
partition using a native Linux kernel API. Header formatting and TCRYPT
header change is not supported, cryptsetup never changes TCRYPT header
on-device.
Cryptsetup supports mapping of TrueCrypt, tcplay or VeraCrypt encrypted partition using a native Linux kernel API.
Header formatting and TCRYPT header change is not supported, cryptsetup never changes TCRYPT header on-device.
TCRYPT extension requires kernel userspace crypto API to be available
(introduced in Linux kernel 2.6.38). If you are configuring kernel
yourself, enable "User-space interface for symmetric key cipher
algorithms" in "Cryptographic API" section
(CRYPTO_USER_API_SKCIPHER .config option).
TCRYPT extension requires kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38).
If you are configuring kernel yourself, enable "User-space interface for symmetric key cipher algorithms" in "Cryptographic API" section (CRYPTO_USER_API_SKCIPHER .config option).
Because TCRYPT header is encrypted, you have to always provide valid
passphrase and keyfiles.
Because TCRYPT header is encrypted, you have to always provide valid passphrase and keyfiles.
Cryptsetup should recognize all header variants, except legacy cipher
chains using LRW encryption mode with 64 bits encryption block (namely
Blowfish in LRW mode is not recognized, this is limitation of kernel
crypto API).
Cryptsetup should recognize all header variants, except legacy cipher chains using LRW encryption mode with 64 bits encryption block (namely Blowfish in LRW mode is not recognized, this is limitation of kernel crypto API).
VeraCrypt is extension of TrueCrypt header with increased iteration
count so unlocking can take quite a lot of time.
VeraCrypt is extension of TrueCrypt header with increased iteration count so unlocking can take quite a lot of time.
To open a VeraCrypt device with a custom Personal Iteration Multiplier
(PIM) value, use either the *--veracrypt-pim=<PIM>* option to directly
specify the PIM on the command- line or use *--veracrypt-query-pim* to
be prompted for the PIM.
To open a VeraCrypt device with a custom Personal Iteration Multiplier (PIM) value, use either the --veracrypt-pim PIM option to directly specify the PIM on the command- line or use --veracrypt-query-pim*to be prompted for the PIM.
The PIM value affects the number of iterations applied during key
derivation. Please refer to
https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html[PIM]
for more detailed information.
The PIM value affects the number of iterations applied during key derivation.
Please refer to https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html[PIM] for more detailed information.
If you need to disable VeraCrypt device support, use
*--disable-veracrypt* option.
If you need to disable VeraCrypt device support, use --disable-veracrypt option.
*NOTE:* Activation with *tcryptOpen* is supported only for cipher chains
using LRW or XTS encryption modes.
*NOTE:* Activation with *tcryptOpen* is supported only for cipher chains using LRW or XTS encryption modes.
The *tcryptDump* command should work for all recognized TCRYPT devices
and doesn't require superuser privilege.
The *tcryptDump* command should work for all recognized TCRYPT devices and doesn't require superuser privilege.
To map system device (device with boot loader where the whole encrypted
system resides) use *--tcrypt-system* option.
Please read specific info in *cryptsetup-tcryptOpen*(8) *--tcrypt-system*
option section as mapping system-encrypted device is tricky.
To map system device (device with boot loader where the whole encrypted system resides) use --tcrypt-system option.
Please read specific info in *cryptsetup-tcryptOpen*(8) --tcrypt-system option section as mapping system-encrypted device is tricky.
To use hidden header (and map hidden device, if available), use
*--tcrypt-hidden* option.
To use hidden header (and map hidden device, if available), use --tcrypt-hidden option.
To explicitly use backup (secondary) header, use *--tcrypt-backup*
option.
To explicitly use backup (secondary) header, use --tcrypt-backup option.
*NOTE:* There is no protection for a hidden volume if the outer volume
is mounted. The reason is that if there were any protection, it would
require some metadata describing what to protect in the outer volume and
the hidden volume would become detectable.
*NOTE:* There is no protection for a hidden volume if the outer volume is mounted.
The reason is that if there were any protection, it would require some metadata describing what to protect in the outer volume and the hidden volume would become detectable.
=== OPEN
*open --type tcrypt <device> <name>* +
tcryptOpen_ <device> <name> (*old syntax*)
Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping
<name>. +
Opens the TCRYPT (a TrueCrypt-compatible) <device> and sets up a mapping <name>. +
See *cryptsetup-open*(8).
=== DUMP
@@ -326,39 +277,27 @@ See *cryptsetup-open*(8).
Dump the header information of a TCRYPT device. +
See *cryptsetup-tcryptDump*(8).
See also https://en.wikipedia.org/wiki/TrueCrypt[TrueCrypt] and
https://en.wikipedia.org/wiki/VeraCrypt[VeraCrypt] pages for more information.
See also https://en.wikipedia.org/wiki/TrueCrypt[TrueCrypt] and https://en.wikipedia.org/wiki/VeraCrypt[VeraCrypt] pages for more information.
Please note that cryptsetup does not use TrueCrypt or VeraCrypt code, please
report all problems related to this compatibility extension to the cryptsetup
project.
Please note that cryptsetup does not use TrueCrypt or VeraCrypt code, please report all problems related to this compatibility extension to the cryptsetup project.
== BITLK (Windows BitLocker compatible) EXTENSION
cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted
partition using a native Linux kernel API. Header formatting and BITLK
header changes are not supported, cryptsetup never changes BITLK header
on-device.
Cryptsetup supports mapping of BitLocker and BitLocker to Go encrypted partition using a native Linux kernel API.
Header formatting and BITLK header changes are not supported, cryptsetup never changes BITLK header on-device.
BITLK extension requires kernel userspace crypto API to be available
(for details see TCRYPT section).
BITLK extension requires kernel userspace crypto API to be available (for details see TCRYPT section).
Cryptsetup should recognize all BITLK header variants, except legacy
header used in Windows Vista systems and partially decrypted BitLocker
devices. Activation of legacy devices encrypted in CBC mode requires at
least Linux kernel version 5.3 and for devices using Elephant diffuser
kernel 5.6.
Cryptsetup should recognize all BITLK header variants, except legacy header used in Windows Vista systems and partially decrypted BitLocker devices.
Activation of legacy devices encrypted in CBC mode requires at least Linux kernel version 5.3 and for devices using Elephant diffuser kernel 5.6.
The *bitlkDump* command should work for all recognized BITLK devices and
doesn't require superuser privilege.
The *bitlkDump* command should work for all recognized BITLK devices and doesn't require superuser privilege.
For unlocking with the *open* a password or a recovery passphrase or a
startup key must be provided.
For unlocking with the *open* a password or a recovery passphrase or a startup key must be provided.
Additionally unlocking using volume key is supported. You must provide
BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file
option. The key must be decrypted and without the header (only
128/256/512 bits of key data depending on used cipher and mode).
Additionally unlocking using volume key is supported.
You must provide BitLocker Full Volume Encryption Key (FVEK) using the --volume-key-file option.
The key must be decrypted and without the header (only 128/256/512 bits of key data depending on used cipher and mode).
Other unlocking methods (TPM, SmartCard) are not supported.
@@ -366,8 +305,7 @@ Other unlocking methods (TPM, SmartCard) are not supported.
*open --type bitlk <device> <name>* +
bitlkOpen <device> <name> (*old syntax*)
Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping
<name>. +
Opens the BITLK (a BitLocker-compatible) <device> and sets up a mapping <name>. +
See *cryptsetup-open*(8).
=== DUMP
@@ -376,32 +314,22 @@ See *cryptsetup-open*(8).
Dump the header information of a BITLK device. +
See *cryptsetup-bitlkDump*(8).
Please note that cryptsetup does not use any Windows BitLocker code,
please report all problems related to this compatibility extension to
the cryptsetup project.
Please note that cryptsetup does not use any Windows BitLocker code, please report all problems related to this compatibility extension to the cryptsetup project.
== FVAULT2 (Apple macOS FileVault2 compatible) EXTENSION
cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk
encryption) by Apple for the macOS operating system using a native Linux
kernel API.
Cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk encryption) by Apple for the macOS operating system using a native Linux kernel API.
*NOTE:* cryptsetup supports only FileVault2 based on Core Storage and HFS+
filesystem (introduced in MacOS X 10.7 Lion).
It does NOT support the new version of FileVault based on the APFS
filesystem used in recent macOS versions.
*NOTE:* Cryptsetup supports only FileVault2 based on Core Storage and HFS+ filesystem (introduced in MacOS X 10.7 Lion).
It does NOT support the new version of FileVault based on the APFS filesystem used in recent macOS versions.
Header formatting and FVAULT2 header changes are not supported;
cryptsetup never changes the FVAULT2 header on-device.
Header formatting and FVAULT2 header changes are not supported; cryptsetup never changes the FVAULT2 header on-device.
FVAULT2 extension requires kernel userspace crypto API to be available
(for details, see TCRYPT section) and kernel driver for HFS+ (hfsplus)
filesystem.
FVAULT2 extension requires kernel userspace crypto API to be available (for details, see TCRYPT section) and kernel driver for HFS+ (hfsplus) filesystem.
Cryptsetup should recognize the basic configuration for portable drives.
The *fvault2Dump* command should work for all recognized FVAULT2 devices
and doesn't require superuser privilege.
The *fvault2Dump* command should work for all recognized FVAULT2 devices and doesn't require superuser privilege.
For unlocking with the *open*, a password must be provided.
Other unlocking methods are not supported.
@@ -410,59 +338,47 @@ Other unlocking methods are not supported.
*open --type fvault2 <device> <name>* +
fvault2Open <device> <name> (*old syntax*)
Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the second
partition on the device) and sets up a mapping <name>. +
Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the second partition on the device) and sets up a mapping <name>. +
See *cryptsetup-open*(8).
== SED (Self Encrypting Drive) OPAL EXTENSION
cryptsetup supports using native hardware encryption on drives that provide an
*OPAL* interface, both nested with *dm-crypt* and standalone. Passphrases,
tokens and metadata are stored using the LUKS2 header format, and are thus
compatible with any software or system that uses LUKS2 (e.g.: tokens).
Cryptsetup supports using native hardware encryption on drives that provide an *OPAL* interface, both nested with *dm-crypt* and standalone.
Passphrases, tokens and metadata are stored using the LUKS2 header format, and are thus compatible with any software or system that uses LUKS2 (e.g.: tokens).
*WARNING:* this support is new and experimental, and requires at least kernel
v6.4. Resizing devices is not supported.
*WARNING:* this support is new and experimental, and requires at least kernel v6.4.
Resizing devices is not supported.
*--hw-opal* can be specified for OPAL + dm-crypt, and
*--hw-opal-only* can be specified to use OPAL only, without a dm-crypt layer.
The --hw-opal can be specified for OPAL + dm-crypt, and --hw-opal-only can be specified to use OPAL only, without a dm-crypt layer.
Opening, closing and enrolling tokens work in the same way as with LUKS2 and
dm-crypt. The new parameters are only necessary when formatting, the LUKS2
metadata will ensure the right setup is performed when opening or closing. If
no *subsystem* is specified, it will be automatically set to *HW-OPAL* so that
it is immediately apparent when a device uses OPAL.
Opening, closing and enrolling tokens work in the same way as with LUKS2 and dm-crypt.
The new parameters are only necessary when formatting, the LUKS2 metadata will ensure the right setup is performed when opening or closing.
If no *subsystem* is specified, it will be automatically set to *HW-OPAL* so that it is immediately apparent when a device uses OPAL.
=== FORMAT
*luksFormat --type luks2 --hw-opal <device> [<key file>]*
Additionally specify *--hw-opal-only* instead of *--hw-opal* to avoid the
dm-crypt layer. Other than the usual passphrase, an admin password will have
to be specified when formatting the first partition of the drive, and will have
to be re-supplied when formatting any other partition until a factory reset
is performed.
Additionally specify --hw-opal-only instead of --hw-opal to avoid the dm-crypt layer.
Other than the usual passphrase, an admin password will have to be specified when formatting the first partition of the drive, and will have to be re-supplied when formatting any other partition until a factory reset is performed.
=== ERASE
*erase <device>*
Securely erase a partition or device. Requires admin password.
Additionally specify *--hw-opal-factory-reset* for a FULL factory reset of the
drive, using the drive's *PSID* (typically printed on the label) instead of the
admin password.
Securely erase a partition or device.
Requires admin password.
Additionally specify --hw-opal-factory-reset for a FULL factory reset of the drive, using the drive's *PSID* (typically printed on the label) instead of the admin password.
*NOTE*: PSID must be entered without any dashes, spaces or underscores.
*WARNING*: a factory reset will cause ALL data on the device to be lost,
regardless of the partition it is ran on, if any, and regardless of any LUKS2
header backup.
*WARNING*: a factory reset will cause ALL data on the device to be lost, regardless of the partition it is ran on, if any, and regardless of any LUKS2 header backup.
== MISCELLANEOUS ACTIONS
=== REPAIR
*repair <device>*
Tries to repair the device metadata if possible. Currently supported
only for LUKS device type. +
Tries to repair the device metadata if possible.
Currently supported only for LUKS device type. +
See *cryptsetup-repair*(8).
=== BENCHMARK
@@ -473,50 +389,38 @@ See *cryptsetup-benchmark*(8).
== PLAIN DM-CRYPT OR LUKS?
Unless you understand the cryptographic background well, use LUKS. With
plain dm-crypt there are a number of possible user errors that massively
decrease security. While LUKS cannot fix them all, it can lessen the
impact for many of them.
Unless you understand the cryptographic background well, use LUKS.
With plain dm-crypt there are a number of possible user errors that massively decrease security.
While LUKS cannot fix them all, it can lessen the impact for many of them.
== WARNINGS
A lot of good information on the risks of using encrypted storage, on
handling problems and on security aspects can be found in the
Cryptsetup FAQ. Read it. Nonetheless, some risks deserve to be
mentioned here.
A lot of good information on the risks of using encrypted storage, on handling problems and on security aspects can be found in the Cryptsetup FAQ.
Read it.
Nonetheless, some risks deserve to be mentioned here.
*Backup:* Storage media die. Encryption has no influence on that. Backup
is mandatory for encrypted data as well, if the data has any worth. See
the Cryptsetup FAQ for advice on how to do a backup of an encrypted
volume.
*Backup:* Storage media die.
Encryption has no influence on that.
Backup is mandatory for encrypted data as well, if the data has any worth.
See the Cryptsetup FAQ for advice on how to do a backup of an encrypted volume.
*Character encoding:* If you enter a passphrase with special symbols,
the passphrase can change depending on character encoding. Keyboard
settings can also change, which can make blind input hard or impossible.
For example, switching from some ASCII 8-bit variant to UTF-8 can lead
to a different binary encoding and hence different passphrase seen by
cryptsetup, even if what you see on the terminal is exactly the same. It
is therefore highly recommended to select passphrase characters only
from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all
ASCII variants and UTF-8.
*Character encoding:* If you enter a passphrase with special symbols, the passphrase can change depending on character encoding.
Keyboard settings can also change, which can make blind input hard or impossible.
For example, switching from some ASCII 8-bit variant to UTF-8 can lead to a different binary encoding and hence different passphrase seen by cryptsetup, even if what you see on the terminal is exactly the same.
It is therefore highly recommended to select passphrase characters only from 7-bit ASCII, as the encoding for 7-bit ASCII stays the same for all ASCII variants and UTF-8.
*LUKS header:* If the header of a LUKS volume gets damaged, all data is
permanently lost unless you have a header-backup. If a key-slot is
damaged, it can only be restored from a header-backup or if another
active key-slot with known passphrase is undamaged. Damaging the LUKS
header is something people manage to do with surprising frequency. This
risk is the result of a trade-off between security and safety, as LUKS
is designed for fast and secure wiping by just overwriting header and
key-slot area.
*LUKS header:* If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header-backup.
If a key-slot is damaged, it can only be restored from a header-backup or if another active key-slot with known passphrase is undamaged.
Damaging the LUKS header is something people manage to do with surprising frequency.
This risk is the result of a trade-off between security and safety, as LUKS is designed for fast and secure wiping by just overwriting header and key-slot area.
*Previously used partitions:* If a partition was previously used, it is
a very good idea to wipe filesystem signatures, data, etc. before
creating a LUKS or plain dm-crypt container on it. For a quick removal
of filesystem signatures, use *wipefs*(8). Take care though that this may
not remove everything. In particular, MD RAID signatures at the end of a
device may survive. It also does not remove data. For a full wipe,
overwrite the whole partition before container creation. If you do not
know how to do that, the cryptsetup FAQ describes several options.
*Previously used partitions:* If a partition was previously used, it is a very good idea to wipe filesystem signatures, data, etc. before creating a LUKS or plain dm-crypt container on it.
For a quick removal of filesystem signatures, use *wipefs*(8).
Take care though that this may not remove everything.
In particular, MD RAID signatures at the end of a device may survive.
It also does not remove data.
For a full wipe, overwrite the whole partition before container creation.
If you do not know how to do that, the cryptsetup FAQ describes several options.
== EXAMPLES
@@ -530,8 +434,7 @@ Example 3: Create LUKS header backup and save it to file.::
Example 4: Open LUKS container on /dev/sdX and map it to sdX_crypt.::
sudo cryptsetup open /dev/sdX sdX_crypt
*WARNING: The command in example 5 will erase all key slots.*::
Your cannot use your LUKS container afterward anymore unless you have
a backup to restore.
Your cannot use your LUKS container afterward anymore unless you have a backup to restore.
Example 5: Erase all key slots on /dev/sdX.::
sudo cryptsetup erase /dev/sdX
Example 6: Restore LUKS header from backup file.::
@@ -542,212 +445,154 @@ Example 6: Restore LUKS header from backup file.::
Cryptsetup returns *0* on success and a non-zero value on error.
Error codes are: *1* wrong parameters, *2* no permission (bad passphrase),
*3* out of memory, *4* wrong device specified, *5* device already exists
or device is busy.
Error codes are: *1* wrong parameters, *2* no permission (bad passphrase), *3* out of memory, *4* wrong device specified, *5* device already exists or device is busy.
== NOTES
=== Passphrase processing for PLAIN mode
Note that no iterated hashing or salting is done in plain mode. If
hashing is done, it is a single direct hash. This means that low-entropy
passphrases are easy to attack in plain mode.
Note that no iterated hashing or salting is done in plain mode.
If hashing is done, it is a single direct hash.
This means that low-entropy passphrases are easy to attack in plain mode.
*From a terminal*: The passphrase is read until the first newline, i.e.
'\n'. The input without the newline character is processed with the
default hash or the hash specified with --hash. The hash result will be
truncated to the key size of the used cipher, or the size specified with
-s.
*From a terminal*: The passphrase is read until the first newline, i.e. '\n'.
The input without the newline character is processed with the default hash or the hash specified with --hash.
The hash result will be truncated to the key size of the used cipher, or the size specified with -s.
*From stdin*: Reading will continue until a newline (or until the
maximum input size is reached), with the trailing newline stripped. The
maximum input size is defined by the same compiled-in default as for the
maximum key file size and can be overwritten using --keyfile-size
option.
*From stdin*: Reading will continue until a newline (or until the maximum input size is reached), with the trailing newline stripped.
The maximum input size is defined by the same compiled-in default as for the maximum key file size and can be overwritten using --keyfile-size option.
The data read will be hashed with the default hash or the hash specified
with --hash. The hash result will be truncated to the key size of the
used cipher, or the size specified with -s.
The data read will be hashed with the default hash or the hash specified with --hash.
The hash result will be truncated to the key size of the used cipher, or the size specified with -s.
Note that if --key-file=- is used for reading the key from stdin,
trailing newlines are not stripped from the input.
Note that if --key-file=- is used for reading the key from stdin, trailing newlines are not stripped from the input.
If "plain" is used as argument to --hash, the input data will not be
hashed. Instead, it will be zero padded (if shorter than the key size)
or truncated (if longer than the key size) and used directly as the
binary key. This is useful for directly specifying a binary key. No
warning will be given if the amount of data read from stdin is less than
the key size.
If "plain" is used as argument to --hash, the input data will not be hashed.
Instead, it will be zero padded (if shorter than the key size) or truncated (if longer than the key size) and used directly as the binary key.
This is useful for directly specifying a binary key.
No warning will be given if the amount of data read from stdin is less than the key size.
*From a key file*: It will be truncated to the key size of the used
cipher or the size given by -s and directly used as a binary key.
*From a key file*: It will be truncated to the key size of the used cipher or the size given by -s and directly used as a binary key.
*WARNING*: The --hash argument is being ignored. The --hash option is
usable only for stdin input in plain mode.
*WARNING*: The --hash argument is being ignored.
The --hash option is usable only for stdin input in plain mode.
If the key file is shorter than the key, cryptsetup will quit with an
error. The maximum input size is defined by the same compiled-in default
as for the maximum key file size and can be overwritten using
--keyfile-size option.
If the key file is shorter than the key, cryptsetup will quit with an error.
The maximum input size is defined by the same compiled-in default as for the maximum key file size and can be overwritten using --keyfile-size option.
=== Passphrase processing for LUKS
LUKS uses PBKDF to protect against dictionary attacks and to give some
protection to low-entropy passphrases (see cryptsetup FAQ).
LUKS uses PBKDF to protect against dictionary attacks and to give some protection to low-entropy passphrases (see cryptsetup FAQ).
*From a terminal*: The passphrase is read until the first newline and
then processed by PBKDF2 without the newline character.
*From a terminal*: The passphrase is read until the first newline and then processed by PBKDF2 without the newline character.
*From stdin*: LUKS will read passphrases from stdin up to the first
newline character or the compiled-in maximum key file length. If
--keyfile-size is given, it is ignored.
*From stdin*: LUKS will read passphrases from stdin up to the first newline character or the compiled-in maximum key file length.
If --keyfile-size is given, it is ignored.
*From key file*: The complete keyfile is read up to the compiled-in
maximum size. Newline characters do not terminate the input. The
--keyfile-size option can be used to limit what is read.
*From key file*: The complete keyfile is read up to the compiled-in maximum size.
Newline characters do not terminate the input.
The --keyfile-size option can be used to limit what is read.
*Passphrase processing*: Whenever a passphrase is added to a LUKS header
(luksAddKey, luksFormat), the user may specify how much the time the
passphrase processing should consume. The time is used to determine the
iteration count for PBKDF2 and higher times will offer better protection
for low-entropy passphrases, but open will take longer to complete. For
passphrases that have entropy higher than the used key length, higher
iteration times will not increase security.
*Passphrase processing*: Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), the user may specify how much the time the passphrase processing should consume.
The time is used to determine the iteration count for PBKDF2 and higher times will offer better protection for low-entropy passphrases, but open will take longer to complete.
For passphrases that have entropy higher than the used key length, higher iteration times will not increase security.
The default setting of one or two seconds is sufficient for most
practical cases. The only exception is a low-entropy passphrase used on
a device with a slow CPU, as this will result in a low iteration count.
On a slow device, it may be advisable to increase the iteration time
using the --iter-time option in order to obtain a higher iteration
count. This does slow down all later luksOpen operations accordingly.
The default setting of one or two seconds is sufficient for most practical cases.
The only exception is a low-entropy passphrase used on a device with a slow CPU, as this will result in a low iteration count.
On a slow device, it may be advisable to increase the iteration time using the --iter-time option in order to obtain a higher iteration count.
This does slow down all later luksOpen operations accordingly.
=== Incoherent behavior for invalid passphrases/keys
LUKS checks for a valid passphrase when an encrypted partition is
unlocked. The behavior of plain dm-crypt is different. It will always
decrypt with the passphrase given. If the given passphrase is wrong, the
device mapped by plain dm-crypt will essentially still contain encrypted
data and will be unreadable.
LUKS checks for a valid passphrase when an encrypted partition is unlocked.
The behavior of plain dm-crypt is different.
It will always decrypt with the passphrase given.
If the given passphrase is wrong, the device mapped by plain dm-crypt will essentially still contain encrypted data and will be unreadable.
=== Supported ciphers, modes, hashes and key sizes
The available combinations of ciphers, modes, hashes and key sizes
depend on kernel support. See /proc/crypto for a list of available
options. You might need to load additional kernel crypto modules in
order to get more options.
The available combinations of ciphers, modes, hashes and key sizes depend on kernel support.
See /proc/crypto for a list of available options.
You might need to load additional kernel crypto modules in order to get more options.
For the --hash option, if the crypto backend is libgcrypt, then all
algorithms supported by the gcrypt library are available. For other
crypto backends, some algorithms may be missing.
For the --hash option, if the crypto backend is libgcrypt, then all algorithms supported by the gcrypt library are available.
For other crypto backends, some algorithms may be missing.
=== Notes on passphrases
Mathematics can't be bribed. Make sure you keep your passphrases safe.
There are a few nice tricks for constructing a fallback, when suddenly
out of the blue, your brain refuses to cooperate. These fallbacks need
LUKS, as it's only possible with LUKS to have multiple passphrases.
Still, if your attacker model does not prevent it, storing your
passphrase in a sealed envelope somewhere may be a good idea as well.
Mathematics can't be bribed.
Make sure you keep your passphrases safe.
There are a few nice tricks for constructing a fallback, when suddenly out of the blue, your brain refuses to cooperate.
These fallbacks need LUKS, as it's only possible with LUKS to have multiple passphrases.
Still, if your attacker model does not prevent it, storing your passphrase in a sealed envelope somewhere may be a good idea as well.
=== Notes on Random Number Generators
Random Number Generators (RNG) used in cryptsetup are always the kernel
RNGs without any modifications or additions to data stream produced.
Random Number Generators (RNG) used in cryptsetup are always the kernel RNGs without any modifications or additions to data stream produced.
There are two types of randomness cryptsetup/LUKS needs. One type (which
always uses /dev/urandom) is used for salts, the AF splitter and for
wiping deleted keyslots.
There are two types of randomness cryptsetup/LUKS needs.
One type (which always uses /dev/urandom) is used for salts, the AF splitter and for wiping deleted keyslots.
The second type is used for the volume key. You can switch between using
/dev/random and /dev/urandom here, see *--use-random* and
*--use-urandom* options. Using /dev/random on a system without enough
entropy sources can cause *luksFormat* to block until the requested
amount of random data is gathered. In a low-entropy situation (embedded
system), this can take a very long time and potentially forever. At the
same time, using /dev/urandom in a low-entropy situation will produce
low-quality keys. This is a serious problem, but solving it is out of
scope for a mere man-page. See *urandom(4)* for more information.
The second type is used for the volume key.
You can switch between using /dev/random and /dev/urandom here, see *--use-random* and *--use-urandom* options.
Using /dev/random on a system without enough entropy sources can cause *luksFormat* to block until the requested amount of random data is gathered.
In a low-entropy situation (embedded system), this can take a very long time and potentially forever.
At the same time, using /dev/urandom in a low-entropy situation will produce low-quality keys.
This is a serious problem, but solving it is out of scope for a mere man-page.
See *urandom(4)* for more information.
=== Authenticated disk encryption (EXPERIMENTAL)
Since Linux kernel version 4.12 dm-crypt supports authenticated disk
encryption.
Since Linux kernel version 4.12 dm-crypt supports authenticated disk encryption.
Normal disk encryption modes are length-preserving (plaintext sector is
of the same size as a ciphertext sector) and can provide only
confidentiality protection, but not cryptographically sound data
integrity protection.
Normal disk encryption modes are length-preserving (plaintext sector is of the same size as a ciphertext sector) and can provide only confidentiality protection, but not cryptographically sound data integrity protection.
Authenticated modes require additional space per-sector for
authentication tag and use Authenticated Encryption with Additional Data
(AEAD) algorithms.
Authenticated modes require additional space per-sector for authentication tag and use Authenticated Encryption with Additional Data (AEAD) algorithms.
If you configure LUKS2 device with data integrity protection, there will
be an underlying dm-integrity device, which provides additional
per-sector metadata space and also provide data journal protection to
ensure atomicity of data and metadata update. Because there must be
additional space for metadata and journal, the available space for the
device will be smaller than for length-preserving modes.
If you configure LUKS2 device with data integrity protection, there will be an underlying dm-integrity device, which provides additional per-sector metadata space and also provide data journal protection to ensure atomicity of data and metadata update.
Because there must be additional space for metadata and journal, the available space for the device will be smaller than for length-preserving modes.
The dm-crypt device then resides on top of such a dm-integrity device.
All activation and deactivation of this device stack is performed by
cryptsetup, there is no difference in using *luksOpen* for integrity
protected devices. If you want to format LUKS2 device with data
integrity protection, use *--integrity* option (see *cryptsetup-luksFormat(8)*).
All activation and deactivation of this device stack is performed by cryptsetup, there is no difference in using *luksOpen* for integrity protected devices.
If you want to format LUKS2 device with data integrity protection, use *--integrity* option (see *cryptsetup-luksFormat(8)*).
Albeit Linux kernel 5.7 added TRIM support for standalone dm-integrity devices,
*cryptsetup(8)* can't offer support for discards (TRIM) in authenticated
encryption mode, because the underlying dm-crypt kernel module does not support
this functionality when dm-integrity is used as auth tag space allocator
(see *--allow-discards* in *cryptsetup-open(8)*).
Albeit Linux kernel 5.7 added TRIM support for standalone dm-integrity devices, *cryptsetup(8)* can't offer support for discards (TRIM) in authenticated encryption mode, because the underlying dm-crypt kernel module does not support this functionality when dm-integrity is used as auth tag space allocator (see *--allow-discards* in *cryptsetup-open(8)*).
Some integrity modes requires two independent keys (key for encryption
and for authentication). Both these keys are stored in one LUKS keyslot.
Some integrity modes requires two independent keys (key for encryption and for authentication).
Both these keys are stored in one LUKS keyslot.
*WARNING:* All support for authenticated modes is experimental and there
are only some modes available for now. Note that there are a very few
authenticated encryption algorithms that are suitable for disk
encryption. You also cannot use CRC32 or any other non-cryptographic
checksums (other than the special integrity mode "none"). If for some
reason you want to have integrity control without using authentication
mode, then you should separately configure dm-integrity independently of
LUKS2.
*WARNING:* All support for authenticated modes is experimental and there are only some modes available for now.
Note that there are a very few authenticated encryption algorithms that are suitable for disk encryption.
You also cannot use CRC32 or any other non-cryptographic checksums (other than the special integrity mode "none").
If for some reason you want to have integrity control without using authentication mode, then you should separately configure dm-integrity independently of LUKS2.
=== Notes on loopback device use
Cryptsetup is usually used directly on a block device (disk partition or
LVM volume). However, if the device argument is a file, cryptsetup tries
to allocate a loopback device and map it into this file. This mode
requires Linux kernel 2.6.25 or more recent which supports the loop
autoclear flag (loop device is cleared on the last close automatically).
Of course, you can always map a file to a loop-device manually. See the
cryptsetup FAQ for an example.
Cryptsetup is usually used directly on a block device (disk partition or LVM volume).
However, if the device argument is a file, cryptsetup tries to allocate a loopback device and map it into this file.
This mode requires Linux kernel 2.6.25 or more recent which supports the loop autoclear flag (loop device is cleared on the last close automatically).
Of course, you can always map a file to a loop-device manually.
See the cryptsetup FAQ for an example.
When device mapping is active, you can see the loop backing file in the
status command output. Also see losetup(8).
When device mapping is active, you can see the loop backing file in the status command output.
Also see losetup(8).
=== LUKS2 header locking
The LUKS2 on-disk metadata is updated in several steps and to achieve
proper atomic update, there is a locking mechanism. For an image in
file, code uses *flock(2)* system call. For a block device, lock is
performed over a special file stored in a locking directory (by default
*/run/cryptsetup*). The locking directory should be created with the
proper security context by the distribution during the boot-up phase.
The LUKS2 on-disk metadata is updated in several steps and to achieve proper atomic update, there is a locking mechanism.
For an image in file, code uses *flock(2)* system call.
For a block device, lock is performed over a special file stored in a locking directory (by default */run/cryptsetup*).
The locking directory should be created with the proper security context by the distribution during the boot-up phase.
Only LUKS2 uses locks, other formats do not use this mechanism.
=== LUKS on-disk format specification
For LUKS on-disk metadata specification see
https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[LUKS1] and
https://gitlab.com/cryptsetup/LUKS2-docs[LUKS2].
For LUKS on-disk metadata specification see https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification[LUKS1] and https://gitlab.com/cryptsetup/LUKS2-docs[LUKS2].
== AUTHORS
Cryptsetup is originally written by mailto:jana@saout.de[Jana Saout]. +
The LUKS extensions and original man page were written by
mailto:clemens@endorphin.org[Clemens Fruhwirth]. +
The LUKS extensions and original man page were written by mailto:clemens@endorphin.org[Clemens Fruhwirth]. +
Man page extensions by mailto:gmazyland@gmail.com[Milan Broz]. +
Man page rewrite and extension by mailto:arno@wagner.name[Arno Wagner].

195
man/integritysetup.8.adoc
View File

@@ -14,14 +14,11 @@ integritysetup - manage dm-integrity (block level integrity) volumes
== DESCRIPTION
Integritysetup is used to configure dm-integrity managed device-mapper
mappings.
Integritysetup is used to configure dm-integrity managed device-mapper mappings.
Device-mapper integrity target provides read-write transparent integrity
checking of block devices. The dm-integrity target emulates an additional
data integrity field per-sector. You can use this additional field
directly with integritysetup utility, or indirectly (for authenticated
encryption) through cryptsetup.
Device-mapper integrity target provides read-write transparent integrity checking of block devices.
The dm-integrity target emulates an additional data integrity field per-sector.
You can use this additional field directly with integritysetup utility, or indirectly (for authenticated encryption) through cryptsetup.
== BASIC ACTIONS
@@ -30,13 +27,9 @@ Integritysetup supports these operations:
=== FORMAT
*format <device>*
Formats <device> (calculates space and dm-integrity superblock and wipes
the device).
Formats <device> (calculates space and dm-integrity superblock and wipes the device).
*<options>* can be [--data-device, --batch-mode, --no-wipe,
--journal-size, --interleave-sectors, --tag-size, --integrity,
--integrity-key-size, --integrity-key-file, --sector-size,
--progress-frequency, --progress-json].
*<options>* can be [--data-device, --batch-mode, --no-wipe, --journal-size, --interleave-sectors, --tag-size, --integrity, --integrity-key-size, --integrity-key-file, --sector-size, --progress-frequency, --progress-json].
=== OPEN
*open <device> <name>* +
@@ -44,16 +37,10 @@ create <name> <device> (OBSOLETE syntax)
Open a mapping with <name> backed by device <device>.
If the integrity algorithm of the device is non-default,
then the algorithm should be specified with the --integrity option.
If the integrity algorithm of the device is non-default, then the algorithm should be specified with the --integrity option.
This will not be detected from the device.
*<options>* can be [--data-device, --batch-mode, --journal-watermark,
--journal-commit-time, --buffer-sectors, --integrity,
--integrity-key-size, --integrity-key-file, --integrity-no-journal,
--integrity-recalculate,
--integrity-recalculate-reset,--integrity-recovery-mode,
--allow-discards].
*<options>* can be [--data-device, --batch-mode, --journal-watermark, --journal-commit-time, --buffer-sectors, --integrity, --integrity-key-size, --integrity-key-file, --integrity-no-journal, --integrity-recalculate, --integrity-recalculate-reset,--integrity-recovery-mode, --allow-discards].
=== CLOSE
*close <name>* +
@@ -61,7 +48,7 @@ remove <name> (OBSOLETE syntax)
Removes existing mapping <name>.
*<options>* can be [--deferred] or [--cancel-deferred]
*<options>* can be [--deferred] or [--cancel-deferred].
=== STATUS
*status <name>*
@@ -78,20 +65,18 @@ Reports parameters from on-disk stored superblock.
Resizes an active mapping <name>.
If --size (in 512-bytes sectors) or --device-size are not specified, the
size is computed from the underlying device. After resize, the
*recalculating* flag is set. If --wipe flag is set and the size of the
device is increased, the newly added section will be wiped.
If --size (in 512-bytes sectors) or --device-size are not specified, the size is computed from the underlying device.
After resize, the *recalculating* flag is set.
If --wipe flag is set and the size of the device is increased, the newly added section will be wiped.
Increasing the size of integrity volumes is available since the Linux
kernel version 5.7, shrinking should work on older kernels too.
Increasing the size of integrity volumes is available since the Linux kernel version 5.7, shrinking should work on older kernels too.
*<options>* can be [--size, --device-size, --wipe].
== OPTIONS
*--allow-discards*::
Allow the use of discard (TRIM) requests for the device. This option
is available since the Linux kernel version 5.7.
Allow the use of discard (TRIM) requests for the device.
This option is available since the Linux kernel version 5.7.
*--batch-mode*, *-q*::
Do not ask for confirmation.
@@ -100,95 +85,76 @@ Do not ask for confirmation.
Bitmap flush time in milliseconds.
+
*WARNING:*
In case of a crash, it is possible that the data and integrity tag
doesn't match if the journal is disabled.
In case of a crash, it is possible that the data and integrity tag doesn't match if the journal is disabled.
*--bitmap-sectors-per-bit* _sectors_::
Number of 512-byte sectors per bitmap bit, the value must be power of
two.
Number of 512-byte sectors per bitmap bit, the value must be power of two.
*--buffer-sectors* _sectors_::
The number of sectors in one buffer.
+
The tag area is accessed using buffers, the large buffer size means that
the I/O size will be larger, but there could be less I/Os issued.
The tag area is accessed using buffers, the large buffer size means that the I/O size will be larger, but there could be less I/Os issued.
*--cancel-deferred*::
Removes a previously configured deferred device removal in *close*
command.
Removes a previously configured deferred device removal in *close* command.
*--data-device* _<data_device>_::
Specify a separate data device that contains existing data. The
<device> then will contain calculated integrity tags and journal for
data on <data_device>.
Specify a separate data device that contains existing data.
The <device> then will contain calculated integrity tags and journal for data on <data_device>.
+
*NOTE:* To not wipe the data device after initial format, also specify
--no-wipe option and activate with --integrity-recalculate to
automatically recalculate integrity tags.
*NOTE:* To not wipe the data device after initial format, also specify --no-wipe option and activate with --integrity-recalculate to automatically recalculate integrity tags.
*--debug*::
Run in debug mode with full diagnostic logs. Debug output lines are
always prefixed by *#*.
Run in debug mode with full diagnostic logs.
Debug output lines are always prefixed by *#*.
*--deferred*::
Defers device removal in *close* command until the last user closes
it.
Defers device removal in *close* command until the last user closes it.
*--help*, *-?*::
Show help text and default parameters.
*--integrity*, *-I* _algorithm_::
Use internal integrity calculation (standalone mode). The integrity
algorithm can be CRC (crc32c/crc32), non-cryptographic hash function
(xxhash64) or hash function (sha1, sha256).
Use internal integrity calculation (standalone mode).
The integrity algorithm can be CRC (crc32c/crc32), non-cryptographic hash function (xxhash64) or hash function (sha1, sha256).
+
For HMAC (hmac-sha256) you have also to specify an integrity key and its
size.
For HMAC (hmac-sha256) you have also to specify an integrity key and its size.
*--integrity-bitmap-mode*, *-B*::
Use alternate bitmap mode (available since Linux kernel 5.2) where
dm-integrity uses bitmap instead of a journal. If a bit in the bitmap
is 1, the corresponding region's data and integrity tags are not
synchronized - if the machine crashes, the unsynchronized regions will
be recalculated. The bitmap mode is faster than the journal mode,
because we don't have to write the data twice, but it is also less
reliable, because if data corruption happens when the machine crashes,
it may not be detected.
Use alternate bitmap mode (available since Linux kernel 5.2) where dm-integrity uses bitmap instead of a journal.
If a bit in the bitmap is 1, the corresponding region's data and integrity tags are not synchronized - if the machine crashes, the unsynchronized regions will be recalculated.
The bitmap mode is faster than the journal mode, because we don't have to write the data twice, but it is also less reliable, because if data corruption happens when the machine crashes, it may not be detected.
*--integrity-inline*::
Store integrity tags to hardware sector integrity fields.
The device must support sectors with additional protection information
(PI, also known as DIF - data integrity field) of the requested size.
Another storage subsystem must not use the additional field
(the device must present a "nop" profile in the kernel).
Note that some devices must be reformatted at a low level to support
this option; for NVMe devices, see nvme(1) id-ns LBA profiles.
The device must support sectors with additional protection information (PI, also known as DIF - data integrity field) of the requested size.
Another storage subsystem must not use the additional field (the device must present a "nop" profile in the kernel).
Note that some devices must be reformatted at a low level to support this option; for NVMe devices, see nvme(1) id-ns LBA profiles.
+
No journal or bitmap is used in this mode. The device should operate
with native speed (without any overhead).
No journal or bitmap is used in this mode.
The device should operate with native speed (without any overhead).
This option is available since the Linux kernel version 6.11.
*--integrity-key-file* _file_::
The file with the integrity key.
*--integrity-key-size* _bytes_::
The size of the data integrity key. Maximum is 4096 bytes.
The size of the data integrity key.
Maximum is 4096 bytes.
*--integrity-no-journal*, *-D*::
Disable journal for integrity device.
*--integrity-recalculate*::
Automatically recalculate integrity tags in kernel on activation. The
device can be used during automatic integrity recalculation but
becomes fully integrity protected only after the background operation
is finished. This option is available since the Linux kernel version
4.19.
Automatically recalculate integrity tags in kernel on activation.
The device can be used during automatic integrity recalculation but becomes fully integrity protected only after the background operation is finished.
This option is available since the Linux kernel version 4.19.
*--integrity-recalculate-reset*::
Restart recalculation from the beginning of the device. It can be used
to change the integrity checksum function. Note it does not change the
tag length. This option is available since the Linux kernel version
5.13.
Restart recalculation from the beginning of the device.
It can be used to change the integrity checksum function.
Note it does not change the tag length.
This option is available since the Linux kernel version 5.13.
*--integrity-recovery-mode*, *-R*::
Recovery mode (no journal, no tag checking).
@@ -197,13 +163,12 @@ Recovery mode (no journal, no tag checking).
The number of interleaved sectors.
*--journal-commit-time* _ms_::
Commit time in milliseconds. When this time passes (and no explicit
flush operation was issued), the journal is written.
Commit time in milliseconds.
When this time passes (and no explicit flush operation was issued), the journal is written.
*--journal-crypt* _algorithm_::
Encryption algorithm for journal data area. You can use a block cipher
here such as cbc-aes or a stream cipher, for example, chacha20 or
ctr-aes.
Encryption algorithm for journal data area.
You can use a block cipher here such as cbc-aes or a stream cipher, for example, chacha20 or ctr-aes.
+
*NOTE:* The journal encryption options are only intended for testing.
Using journal encryption does not make sense without encryption of the data.
@@ -212,37 +177,38 @@ Using journal encryption does not make sense without encryption of the data.
The file with the journal encryption key.
*--journal-crypt-key-size* _bytes_::
The size of the journal encryption key. Maximum is 4096 bytes.
The size of the journal encryption key.
Maximum is 4096 bytes.
*--journal-integrity* _algorithm_::
Integrity algorithm for journal area. See --integrity option for
detailed specification.
Integrity algorithm for journal area.
See --integrity option for detailed specification.
*--journal-integrity-key-file* _file_::
The file with the integrity key.
*--journal-integrity-key-size* _bytes_::
The size of the journal integrity key. Maximum is 4096 bytes.
The size of the journal integrity key.
Maximum is 4096 bytes.
*--journal-size*, *-j* _butes_::
Size of the journal.
*--journal-watermark* _percent_::
Journal watermark in percents. When the size of the journal exceeds
this watermark, the journal flush will be started.
Journal watermark in percents.
When the size of the journal exceeds this watermark, the journal flush will be started.
*--no-wipe*::
Do not wipe the device after format. A device that is not initially
wiped will contain invalid checksums.
Do not wipe the device after format.
A device that is not initially wiped will contain invalid checksums.
*--progress-frequency* _seconds_::
Print separate line every <seconds> with wipe progress.
*--progress-json*::
Prints wipe progress data in json format suitable mostly for machine
processing. It prints separate line every half second (or based on
--progress-frequency value). The JSON output looks as follows during
wipe progress (except it's compact single line):
Prints wipe progress data in json format suitable mostly for machine processing.
It prints separate line every half second (or based on --progress-frequency value).
The JSON output looks as follows during wipe progress (except it's compact single line):
+
....
{
@@ -255,19 +221,15 @@ wipe progress (except it's compact single line):
}
....
+
Note on numbers in JSON output: Due to JSON parsers limitations all
numbers are represented in a string format due to need of full 64bit
unsigned integers.
Note on numbers in JSON output: Due to JSON parsers limitations all numbers are represented in a string format due to need of full 64bit unsigned integers.
*--sector-size*, *-s* _bytes_::
Sector size (power of two: 512, 1024, 2048, 4096).
*--tag-size*, *-t* _bytes_::
Size of the integrity tag per-sector (here the integrity function will
store authentication tag).
Size of the integrity tag per-sector (here the integrity function will store authentication tag).
+
*NOTE:* The size can be smaller that output size of the hash function,
in that case only part of the hash will be stored.
*NOTE:* The size can be smaller that output size of the hash function, in that case only part of the hash will be stored.
*--usage*::
Show short option help.
@@ -279,15 +241,13 @@ Print more information on command execution.
Show the program version.
*--wipe*::
Wipe the newly allocated area after resize to bigger size. If this
flag is not set, checksums will be calculated for the data previously
stored in the newly allocated area.
Wipe the newly allocated area after resize to bigger size.
If this flag is not set, checksums will be calculated for the data previously stored in the newly allocated area.
== LEGACY COMPATIBILITY OPTIONS
*WARNING:*::
Do not use these options until you need compatibility with specific
old kernel.
Do not use these options until you need compatibility with specific old kernel.
*--integrity-legacy-padding*::
Use inefficient legacy padding.
@@ -296,22 +256,18 @@ Use inefficient legacy padding.
Use old flawed HMAC calculation (also does not protect superblock).
*--integrity-legacy-recalculate*::
Allow insecure recalculating of volumes with HMAC keys (recalculation
offset in superblock is not protected).
Allow insecure recalculating of volumes with HMAC keys (recalculation offset in superblock is not protected).
== RETURN CODES
Integritysetup returns *0* on success and a non-zero value on error.
Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
*4* wrong device specified, *5* device already exists or device is busy.
Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4* wrong device specified, *5* device already exists or device is busy.
== NOTES
The dm-integrity target is available since Linux kernel version 4.12.
Format and activation of an integrity device always require superuser
privilege because the superblock is calculated and handled in
dm-integrity kernel target.
Format and activation of an integrity device always require superuser privilege because the superblock is calculated and handled in dm-integrity kernel target.
== EXAMPLES
@@ -325,13 +281,11 @@ Open the device with default parameters:
Format the device in standalone mode for use with HMAC(SHA256):
*integritysetup format <device> --tag-size 32 --integrity hmac-sha256
--integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
*integritysetup format <device> --tag-size 32 --integrity hmac-sha256 --integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
Open (activate) the device with HMAC(SHA256) and HMAC key in file:
*integritysetup open <device> test --integrity hmac-sha256
--integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
*integritysetup open <device> test --integrity hmac-sha256 --integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
Dump dm-integrity superblock information:
@@ -339,8 +293,7 @@ Dump dm-integrity superblock information:
== DM-INTEGRITY ON-DISK FORMAT
The on-disk format specification available at
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[DMIntegrity] page.
The on-disk format specification available at https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[DMIntegrity] page.
== AUTHORS

230
man/veritysetup.8.adoc
View File

@@ -14,11 +14,9 @@ veritysetup - manage dm-verity (block level verification) volumes
== DESCRIPTION
Veritysetup is used to configure dm-verity managed device-mapper
mappings.
Veritysetup is used to configure dm-verity managed device-mapper mappings.
Device-mapper verity target provides read-only transparent integrity
checking of block devices using kernel crypto API.
Device-mapper verity target provides read-only transparent integrity checking of block devices using kernel crypto API.
The dm-verity devices are always read-only.
@@ -29,65 +27,51 @@ Veritysetup supports these operations:
=== FORMAT
*format <data_device> <hash_device>*
Calculates and permanently stores hash verification data for
data_device. Hash area can be located on the same device after data if
specified by --hash-offset option.
Calculates and permanently stores hash verification data for data_device.
Hash area can be located on the same device after data if specified by --hash-offset option.
Note you need to provide root hash string for device verification or
activation. Root hash must be trusted.
Note you need to provide root hash string for device verification or activation.
Root hash must be trusted.
The data or hash device argument can be block device or file image. If
hash device path doesn't exist, it will be created as file.
The data or hash device argument can be block device or file image.
If hash device path doesn't exist, it will be created as file.
*<options>* can be [--hash, --no-superblock, --format,
--data-block-size, --hash-block-size, --data-blocks, --hash-offset,
--salt, --uuid, --root-hash-file].
*<options>* can be [--hash, --no-superblock, --format, --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid, --root-hash-file].
If option --root-hash-file is used, the root hash is stored in
hex-encoded text format in <path>.
If option --root-hash-file is used, the root hash is stored in hex-encoded text format in <path>.
=== OPEN
*open <data_device> <name> <hash_device> <root_hash>* +
*open <data_device> <name> <hash_device> --root-hash-file <path>* +
create <name> <data_device> <hash_device> <root_hash> (OBSOLETE syntax)
Creates a mapping with <name> backed by device <data_device> and using
<hash_device> for in-kernel verification.
Creates a mapping with <name> backed by device <data_device> and using <hash_device> for in-kernel verification.
The <root_hash> is a hexadecimal string.
*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption
or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks,
--check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets,
--shared].
*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks, --check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets, --shared].
If option --root-hash-file is used, the root hash is read from <path>
instead of from the command line parameter. Expects hex-encoded text,
without terminating newline.
If option --root-hash-file is used, the root hash is read from <path> instead of from the command line parameter.
Expects hex-encoded text, without terminating newline.
If option --no-superblock is used, you have to use as the same options
as in initial format operation.
If option --no-superblock is used, you have to use as the same options as in initial format operation.
=== VERIFY
*verify <data_device> <hash_device> <root_hash>* +
*verify <data_device> <hash_device> --root-hash-file <path>*
Verifies data on data_device with use of hash blocks stored on
hash_device.
Verifies data on data_device with use of hash blocks stored on hash_device.
This command performs userspace verification, no kernel device is
created.
This command performs userspace verification, no kernel device is created.
The <root_hash> is a hexadecimal string.
If option --root-hash-file is used, the root hash is read from <path>
instead of from the command line parameter. Expects hex-encoded text,
without terminating newline.
If option --root-hash-file is used, the root hash is read from <path> instead of from the command line parameter.
Expects hex-encoded text, without terminating newline.
*<options>* can be [--hash-offset, --no-superblock, --root-hash-file].
If option --no-superblock is used, you have to use as the same options
as in initial format operation.
If option --no-superblock is used, you have to use as the same options as in initial format operation.
=== CLOSE
*close <name>* +
@@ -114,105 +98,95 @@ Reports parameters of verity device from on-disk stored superblock.
Do not ask for confirmation.
*--cancel-deferred*::
Removes a previously configured deferred device removal in *close*
command.
Removes a previously configured deferred device removal in *close* command.
*--check-at-most-once*::
Instruct kernel to verify blocks only the first time they are read
from the data device, rather than every time.
Instruct kernel to verify blocks only the first time they are read from the data device, rather than every time.
+
*WARNING:* It provides a reduced level of security because only offline
tampering of the data device's content will be detected, not online
tampering. This option is available since Linux kernel version 4.17.
*WARNING:* It provides a reduced level of security because only offline tampering of the data device's content will be detected, not online tampering.
This option is available since Linux kernel version 4.17.
*--data-blocks* _blocks_::
Size of data device used in verification. If not specified, the whole
device is used.
Size of data device used in verification.
If not specified, the whole device is used.
*--data-block-size* _bytes_::
Used block size for the data device. (Note kernel supports only
page-size as maximum here.)
Used block size for the data device.
(Note kernel supports only page-size as maximum here.)
*--debug*::
Run in debug mode with full diagnostic logs. Debug output lines are
always prefixed by *#*.
Run in debug mode with full diagnostic logs.
Debug output lines are always prefixed by *#*.
*--deferred*::
Defers device removal in *close* command until the last user closes
it.
Defers device removal in *close* command until the last user closes it.
*--error-as-corruption*::
Handle device I/O errors the same as data corruption. This option must
be combined with --restart-on-corruption or --panic-on-corruption.
Handle device I/O errors the same as data corruption.
This option must be combined with --restart-on-corruption or --panic-on-corruption.
*--fec-device* _device_::
Use forward error correction (FEC) to recover from corruption if hash
verification fails. Use encoding data from the specified device.
Use forward error correction (FEC) to recover from corruption if hash verification fails.
Use encoding data from the specified device.
+
The fec device argument can be block device or file image. For format,
if fec device path doesn't exist, it will be created as file.
The fec device argument can be block device or file image.
For format, if fec device path doesn't exist, it will be created as file.
+
Block sizes for data and hash devices must match. Also, if the verity
data_device is encrypted the fec_device should be too.
Block sizes for data and hash devices must match.
Also, if the verity data_device is encrypted the fec_device should be too.
+
FEC calculation covers data, hash area, and optional foreign metadata
stored on the same device with the hash tree (additional space after
hash area). Size of this optional additional area protected by FEC is
calculated from image sizes, so you must be sure that you use the same
images for activation.
FEC calculation covers data, hash area, and optional foreign metadata stored on the same device with the hash tree (additional space after hash area).
Size of this optional additional area protected by FEC is calculated from image sizes, so you must be sure that you use the same images for activation.
+
If the hash device is in a separate image, metadata covers the whole
rest of the image after the hash area.
If the hash device is in a separate image, metadata covers the whole rest of the image after the hash area.
+
If hash and FEC device is in the image, metadata ends on the FEC area
offset.
If hash and FEC device is in the image, metadata ends on the FEC area offset.
*--fec-offset* _bytes_::
This is the offset, in bytes, from the start of the FEC device to the
beginning of the encoding data.
This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data.
*--fec-roots* _number_::
Number of generator roots. This equals to the number of parity bytes
in the encoding data. In RS(M, N) encoding, the number of roots is
M-N. M is 255 and M-N is between 2 and 24 (including).
Number of generator roots.
This equals to the number of parity bytes in the encoding data.
In RS(M, N) encoding, the number of roots is M-N.
M is 255 and M-N is between 2 and 24 (including).
*--format* _number_::
Specifies the hash version type. Format type 0 is original Chrome OS
version. Format type 1 is current version.
Specifies the hash version type.
Format type 0 is original Chrome OS version.
Format type 1 is current version.
*--hash* _hash_::
Hash algorithm for dm-verity. For default see --help option.
Hash algorithm for dm-verity.
For default see --help option.
*--hash-block-size* _bytes_::
Used block size for the hash device. (Note kernel supports only
page-size as maximum here.)
Used block size for the hash device.
(Note kernel supports only page-size as maximum here.)
*--hash-offset* _bytes_::
Offset of hash area/superblock on hash_device. Value must be aligned
to disk sector offset.
Offset of hash area/superblock on hash_device.
Value must be aligned to disk sector offset.
*--help*, *-?*::
Show help text and default parameters.
*--ignore-corruption*, *--restart-on-corruption*, *--panic-on-corruption*::
Defines what to do if data integrity problem is detected (data
corruption).
Defines what to do if data integrity problem is detected (data corruption).
+
Without these options kernel fails the IO operation with I/O error. With
--ignore-corruption option the corruption is only logged. With
--restart-on-corruption or --panic-on-corruption the kernel is restarted
(panicked) immediately. (You have to provide way how to avoid restart
loops.)
Without these options kernel fails the IO operation with I/O error.
With --ignore-corruption option the corruption is only logged.
With --restart-on-corruption or --panic-on-corruption the kernel is restarted (panicked) immediately.
(You have to provide way how to avoid restart loops.)
+
*WARNING:* Use these options only for very specific cases. These options
are available since Linux kernel version 4.1.
*WARNING:* Use these options only for very specific cases.
These options are available since Linux kernel version 4.1.
*--ignore-zero-blocks*::
Instruct kernel to not verify blocks that are expected to contain
zeroes and always directly return zeroes instead.
Instruct kernel to not verify blocks that are expected to contain zeroes and always directly return zeroes instead.
+
*WARNING:* Use this option only in very specific cases. This option is
available since Linux kernel version 4.5.
*WARNING:* Use this option only in very specific cases.
This option is available since Linux kernel version 4.5.
*--no-superblock*::
Create or use dm-verity without permanent on-disk superblock.
@@ -221,17 +195,16 @@ Create or use dm-verity without permanent on-disk superblock.
Path to file with stored root hash in hex-encoded text.
*--root-hash-signature* _file_*::
Path to root hash signature file used to verify the root hash (in
kernel). This feature requires Linux kernel version 5.4 or more
recent.
Path to root hash signature file used to verify the root hash (in kernel).
This feature requires Linux kernel version 5.4 or more recent.
*--salt=hex string*::
Salt used for format or verification. Format is a hexadecimal string.
Salt used for format or verification.
Format is a hexadecimal string.
*--shared*::
Allows data device to be used in shared mode. The data device is not checked
for exclusive access in-before the device activation and may be mapped in multiple
verity mappings.
Allows data device to be used in shared mode.
The data device is not checked for exclusive access in-before the device activation and may be mapped in multiple verity mappings.
*--usage*::
Show short option help.
@@ -241,11 +214,9 @@ Try to use kernel tasklets in dm-verity driver for performance reasons.
This option is available since Linux kernel version 6.0.
*--uuid* _UUID_::
Use the provided UUID for format command instead of generating new
one.
Use the provided UUID for format command instead of generating new one.
+
The UUID must be provided in standard UUID format, e.g.
12345678-1234-1234-1234-123456789abc.
The UUID must be provided in standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc.
*--verbose*, *-v*::
Print more information on command execution.
@@ -257,64 +228,51 @@ Show the program version.
Veritysetup returns *0* on success and a non-zero value on error.
Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
*4* wrong device specified, *5* device already exists or device is busy.
Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4* wrong device specified, *5* device already exists or device is busy.
== EXAMPLES
*veritysetup --data-blocks=256 format <data_device> <hash_device>*
Calculates and stores verification data on hash_device for the first 256
blocks (of block-size). If hash_device does not exist, it is created (as
file image).
Calculates and stores verification data on hash_device for the first 256 blocks (of block-size).
If hash_device does not exist, it is created (as file image).
*veritysetup format --root-hash-file <path> <data_device> <hash_device>*
Calculates and stores verification data on hash_device for the whole
data_device, and store the root hash as hex-encoded text in <path>.
Calculates and stores verification data on hash_device for the whole data_device, and store the root hash as hex-encoded text in <path>.
*veritysetup --data-blocks=256 --hash-offset=1052672 format <device>
<device>*
*veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <device>*
Verification data (hashes) is stored on the same device as data
(starting at hash-offset). Hash-offset must be greater than number of
blocks in data-area.
Verification data (hashes) is stored on the same device as data (starting at hash-offset).
Hash-offset must be greater than number of blocks in data-area.
*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device
<device> <device> <root_hash>*
*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device <device> <device> <root_hash>*
Activates the verity device named test-device. Options --data-blocks and
--hash-offset are the same as in the format command. The <root_hash> was
calculated in format command.
Activates the verity device named test-device.
Options --data-blocks and --hash-offset are the same as in the format command.
The <root_hash> was calculated in format command.
*veritysetup --data-blocks=256 --hash-offset=1052672 verify
<data_device> <hash_device> <root_hash>*
*veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash>*
Verifies device without activation (in userspace).
*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
<path> verify <data_device> <hash_device>*
*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file <path> verify <data_device> <hash_device>*
Verifies device without activation (in userspace). Root hash passed via
a file rather than inline.
Verifies device without activation (in userspace).
Root hash passed via a file rather than inline.
*veritysetup --fec-device=<fec_device> --fec-roots=10 format
<data_device> <hash_device>*
*veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device>*
Calculates and stores verification and encoding data for data_device.
== DM-VERITY ON-DISK SPECIFICATION
The on-disk format specification is available at
https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page.
The on-disk format specification is available at https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page.
== AUTHORS
The first implementation of veritysetup was written by Chrome OS
authors.
The first implementation of veritysetup was written by Chrome OS authors.
This version is based on verification code written by
mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup
by mailto:gmazyland@gmail.com[Milan Broz].
This version is based on verification code written by mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup by mailto:gmazyland@gmail.com[Milan Broz].
include::man/common_footer.adoc[]