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: Grammar and simple stylistic fixes.

Browse Source 
This is based mainly on Grammarly.

It unifies man pages to at least some level of grammar,
so later we can focus on adding more readable content.
This commit is contained in:
Milan Broz
2025-07-10 11:10:35 +02:00
parent 1438140ce3
commit 360f85dde7
29 changed files with 585 additions and 586 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
man/common_footer.adoc
View File

@@ -2,7 +2,7 @@
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.
Please attach the output of the failed command with --debug option added.
== SEE ALSO

513
man/common_options.adoc
View File

File diff suppressed because it is too large Load Diff

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

@@ -16,18 +16,18 @@ 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 a few common configurations.
To benchmark other ciphers or modes, you need to specify --cipher and --key-size options.
To benchmark other ciphers or modes, 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.
*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 the kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38).
If you are configuring the 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].

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

@@ -19,7 +19,7 @@ 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.
You have to provide a password or keyfile to dump the 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.

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

@@ -18,7 +18,7 @@ cryptsetup-close - removes the existing mapping <name> (and the associated key)
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 the same, device type is determined automatically from the active device).
*<options>* can be [--deferred, --cancel-deferred, --header, --disable-locks].

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

@@ -17,15 +17,15 @@ 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.
The conversion will not be performed if there is an additional LUKS2 feature or LUKS1 has an 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.
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 an inactive device.
There must not be an active dm-crypt mapping established for the LUKS header requested for conversion.
The *--type* option is mandatory with the following accepted values: _luks1_ or _luks2_.

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

@@ -18,11 +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 run 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].

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

@@ -19,7 +19,7 @@ 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.
You have to provide a password or keyfile to dump the 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.

4
man/cryptsetup-isLuks.8.adoc
View File

@@ -16,12 +16,12 @@ cryptsetup-isLuks - check if a device is a LUKS device
== DESCRIPTION
Returns true, if <device> is a LUKS device, false otherwise.
Returns true if <device> is a LUKS device, false otherwise.
Use option -v to get human-readable feedback.
'Command successful.' means the device is a LUKS device.
By specifying --type you may query for specific LUKS version.
By specifying --type, you may query for a specific LUKS version.
*<options>* can be [--header, --type, --disable-locks].

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

@@ -18,16 +18,16 @@ cryptsetup-luksAddKey - add a new passphrase
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).
Alternatively to the existing passphrase, the user may pass directly the 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.
Existing passphrase for any active keyslot is not required.
If you don't pass a new key via --volume-key-file option, a new random key is generated.
The 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 the LUKS2 format that supports per-keyslot parameters.
For LUKS1, the PBKDF type and hash algorithm are 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].
@@ -35,13 +35,13 @@ include::man/common_options.adoc[]
== EXAMPLES
*NOTE*: When not specified otherwise interactive passphrase prompt is always default method.
*NOTE*: The interactive passphrase prompt is always the default method when not specified otherwise.
Add new keyslot using interactive passphrase prompt for both existing and new passphrase:
Add new keyslot using interactive passphrase prompt for both existing and new passphrases:
*cryptsetup luksAddKey /dev/device*
Add new keyslot using LUKS2 tokens to unlock existing keyslot with interactive passphrase prompt for new passphrase:
Add a new keyslot using LUKS2 tokens to unlock the existing keyslot with an interactive passphrase prompt for the new passphrase:
*cryptsetup luksAddKey --token-only /dev/device*

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

@@ -20,17 +20,17 @@ 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 keyslot is specified (via --key-slot), the passphrase for that keyslot must be given, and the new passphrase will overwrite the specified keyslot.
If no keyslot is specified and there is still a free keyslot, then the new passphrase will be put into a free keyslot before the keyslot containing the old passphrase is purged.
If there is no free keyslot, then the keyslot 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 keyslot is overwritten, a media failure during this operation can cause the overwrite to fail after the old passphrase has been wiped, making the LUKS container inaccessible.
LUKS2 mitigates that by never overwriting the existing keyslot area as long as there's a free space in the 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 avoid leaking 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 the LUKS2 format that supports per-keyslot parameters.
For LUKS1, the PBKDF type and hash algorithm are 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].

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

@@ -17,14 +17,14 @@ 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.
The passphrase for the 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 no keyslot is specified and there is still a free keyslot, 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, the keyslot with the old parameters is directly overwritten.
*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, making 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].

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

@@ -19,17 +19,17 @@ 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.
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.
A passphrase must be supplied to dump the volume key, 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.
To dump an unbound key (LUKS2 format only), --unbound parameter, specific --key-slot id and proper passphrase must be supplied, 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].

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

@@ -16,14 +16,14 @@ 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 keyslot 0) via prompting or <key file>.
Note that if the second argument is present, the passphrase is taken from the file given there, without using the --key-file option.
Also note that for both forms of reading the passphrase from a file, you can give '-' as a 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., a mounted filesystem, used in LVM, active RAID member, etc.
The device or filesystem has to be unmounted in order to call luksFormat.
To use specific version of LUKS format, use _--type luks1_ or _type luks2_.
To use a 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.

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

@@ -17,14 +17,13 @@ cryptsetup-luksHeaderBackup - store a binary backup of the LUKS header and keysl
== DESCRIPTION
Stores a binary backup of the LUKS header and keyslot area. +
*NOTE:* Using '-' as filename writes the header backup to a file named
'-'.
*NOTE:* Using '-' as a filename writes the header backup to a file named '-'.
*<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.
*WARNING:* This backup file and a passphrase valid at the time of backup allow 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 wipe the LUKS device securely by just overwriting the header and keyslots.
You must either securely erase all header backups or overwrite the encrypted data area.
The second option is less secure, as some sectors can survive, e.g., due to defect management.
include::man/common_options.adoc[]

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

@@ -17,14 +17,14 @@ 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. +
*NOTE:* Using '-' as filename reads the header backup from a file named '-'.
*NOTE:* Using '-' as a 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 the header backup match.
Alternatively, the backup will also be written if there is no LUKS header on the device.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

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

@@ -8,17 +8,17 @@
== Name
cryptsetup-luksKillSlot - wipe a key-slot from the LUKS device
cryptsetup-luksKillSlot - wipe a keyslot from the LUKS device
== SYNOPSIS
*cryptsetup _luksKillSlot_ [<options>] <device> <key slot number>*
*cryptsetup _luksKillSlot_ [<options>] <device> <number>*
== 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.
Wipe the keyslot with the number 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 keyslot, 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].
@@ -26,7 +26,7 @@ Removing the last passphrase makes a 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 no passphrase is provided (on stdin or through --key-file argument) and batch-mode (-q) is active, the keyslot is removed without any other warning.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

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

@@ -21,7 +21,7 @@ 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.
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 must use _luksResume_ to reinstate the encryption key and unblock the device or _close_ to remove the mapped device.
*<options>* can be [--header, --disable-locks].

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

@@ -19,7 +19,7 @@ Opens (creates a mapping with) <name> backed by device <device>.
Device type can be _plain_, _luks_ (default), _luks1_, _luks2_, _loopaes_ or _tcrypt_.
For backward compatibility there are *open* command aliases:
For backward compatibility, there are *open* command aliases:
*create* (argument-order <name> <device>): open --type plain +
*plainOpen*: open --type plain +
@@ -28,8 +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> +
@@ -38,10 +38,10 @@ 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 differ 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.
The key in the 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.
@@ -55,7 +55,7 @@ To map the encrypted device /dev/sda10 to the decrypted device /dev/mapper/e1, y
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 the keyring with the key and remove the 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*
@@ -69,10 +69,10 @@ luksOpen <device> <name> (old syntax)
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 a token does not exist (or fails to unlock keyslot) and 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 a valid LUKS2 token but it requires a PIN to unlock the assigned keyslot, it is not used unless one of the following options is added: --token-only,
--token-type where type matches the desired PIN-protected token or --token-id with id matching the 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].
@@ -86,17 +86,17 @@ If the key file is encrypted with GnuPG, then you have to use --key-file=- and d
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.
Note that the units need to be specified in terms 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.
If the original device used an offset but did not use it in IV sector calculations, you must 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).
@@ -111,16 +111,16 @@ 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].
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, which can be repeated.
Note that using keyfiles is compatible with TCRYPT and differs 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).
This could speed up unlocking the device (but also 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 in 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).
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>* +
@@ -130,8 +130,8 @@ 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].
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.
When using --volume-key-file, the device will be opened even if the provided key is incorrect.
=== FileVault2
*open --type fvault2 <device> <name>* +

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

@@ -26,17 +26,17 @@ 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 the 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).
*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 avoid leaking 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).
The reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c).
The same applies to the 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).
For in-place encryption mode, the _reencrypt_ action additionally takes all options available for the _luksFormat_ action for the 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.
@@ -88,22 +88,22 @@ See *cryptsetup-luksFormat*(8).
== 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.
With the <device> parameter, cryptsetup looks up the active <device> dm mapping.
If no active mapping is detected, it starts offline LUKS2 reencryption; otherwise, online reencryption occurs.
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, or power off), it may require recovery.
The recovery is run automatically on next activation (action _open_) when needed or explicitly by the 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.
The optional parameter <new_name> takes effect only with the encrypt option, and it activates device <new_name> immediately after encryption initialization is finished.
That's useful when the 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).
The current working directory must be writable, and temporary files created during reencryption must be present.
During reencryption, 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).
@@ -116,17 +116,17 @@ include::man/common_options.adoc[]
=== 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):
Make sure the 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):
Make sure the 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*
Encrypt LUKS2 device (in-place) with detached header put in a file:
Encrypt LUKS2 device (in-place) with detached header, put in a file:
*cryptsetup reencrypt --encrypt --type luks2 --header my_luks2_header /dev/plaintext_device*
@@ -134,7 +134,7 @@ Initialize LUKS2 in-place encryption operation only and activate the device (not
*cryptsetup reencrypt --encrypt --type luks2 --init-only --reduce-device-size 32m /dev/plaintext_device my_future_luks_device*
Resume online encryption on device initialized in example above:
Resume online encryption on the device initialized in the example above:
*cryptsetup reencrypt --resume-only /dev/plaintext_device* or
*cryptsetup reencrypt --active-name my_future_luks_device*
@@ -145,19 +145,19 @@ Reencrypt LUKS2 device (refresh volume key only):
*cryptsetup reencrypt /dev/encrypted_device*
Reencrypt LUKS2 device using keyslot(s) associated to the token 3.
Reencrypt LUKS2 device using keyslot(s) associated with the token 3.
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.
Reencrypt LUKS2 device using keyslots associated with all 'systemd-tpm2' tokens.
All other keyslots will be removed after the reencryption finishes.
*cryptsetup reencrypt --token-type systemd-tpm2 /dev/encrypted_device*
=== LUKS2 DECRYPTION EXAMPLES
Decrypt LUKS2 device with header put in head of data device (header file does not exist):
Decrypt LUKS2 device with header put in the head of the data device (header file does not exist):
*cryptsetup reencrypt --decrypt --header /export/header/to/file /dev/encrypted_device*

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

@@ -18,14 +18,14 @@ 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.
Update parameters of active device <name> without the need to deactivate the device (and unmount the filesystem).
Currently, it supports parameter refresh on the 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.
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 the 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 the default setting (respective to device type).
*LUKS2 only:*
@@ -33,7 +33,7 @@ The --integrity-no-journal parameter affects only LUKS2 devices with the underly
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 the volume key passed in the 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].

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

@@ -19,21 +19,21 @@ cryptsetup-repair - repair the device metadata
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.
This command is useful for fixing 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.
This command will only change the LUKS header, not any keyslot 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.
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 while writing the reencryption segment, the repair command can perform reencryption recovery so that reencryption can continue later.
Repairing reencryption requires verification of the reencryption keyslot, so a 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.
Corruption of a keyslot results in a situation where a known password is no longer accepted.
It can happen due to storage media failure or overwriting the keyslot area with other data.
Only certain corruptions, usually only a low-entropy area (like zeroed blocks), can be detected.
The detection prints only warnings.
@@ -42,7 +42,7 @@ It can also print more specific offsets on the device for detailed manual inspec
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.
You have to use the LUKS header backup.
*<options>* can be [--timeout, --verify-passphrase, --disable-locks, --type, --header, --key-file, --keyfile-size, --keyfile-offset, --key-slot].

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

@@ -18,13 +18,13 @@ 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-byte sectors) or --device-size is 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 the LUKS header (see data payload offset in the *luksDump* command).
For a 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.
If cryptsetup detected a volume key for the active device loaded in the kernel keyring service, the 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.

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

@@ -14,10 +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 a 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 keyslot.
See *cryptsetup*(8) for instructions on how to remove, import or export the token.
=== Add operation
@@ -25,7 +25,7 @@ See *cryptsetup(8)* for instructions on how to remove, import or export the toke
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.
The specified SSH server must contain a key file on the specified path with a passphrase for an existing keyslot 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.
@@ -43,7 +43,7 @@ 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.
If not specified, the token will be assigned to the first keyslot matching the provided passphrase.
*--ssh-keypath* _string_::
Path to the SSH key for connecting to the remote server.
@@ -55,7 +55,7 @@ Path to the key file on the remote server.
IP address/URL of the remote server for this token.
*--ssh-user* _string_::
Username used for the remote server.
The username used for the remote server.
*--verbose*, *-v*::
Shows more detailed error messages

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

@@ -18,14 +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.
If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of the TCRYPT header info.
Beware that the volume key (or concatenated volume keys if a 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].
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, which can be repeated.
include::man/common_options.adoc[]
include::man/common_footer.adoc[]

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

@@ -17,27 +17,27 @@ 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.
For the auto-activation, the passphrase must be stored in the keyring with the specified description.
Usually, the passphrase should be stored in the _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.
For adding a new keyring token, the option --key-description is mandatory.
Also, a new token is assigned to the keyslot specified with --key-slot option or to all active keyslots if the --key-slot option is omitted.
To remove existing token, specify the token ID which should be removed with --token-id option.
To remove an existing token, specify the token ID that 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.
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 an arbitrary valid JSON data in the LUKS2 token.
It may be passed via standard input or a file passed in --json-file option.
If you specify --key-slot, a successfully imported token is also assigned to the keyslot.
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.
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 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].

186
man/cryptsetup.8.adoc
View File

@@ -14,14 +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.
cryptsetup is used to conveniently set up 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.
The difference is that LUKS uses a metadata header and can 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 using loop-AES volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes, and 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 a specific cryptsetup action, see *cryptsetup-<action>*(8), where *<action>* is the name of the cryptsetup action.
== BASIC ACTIONS
@@ -66,7 +66,7 @@ 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.
No checks are performed, and 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>.
@@ -83,33 +83,33 @@ 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.
It adds a standardized header at the start of the device, a keyslot 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.
But note that when the LUKS header is at a non-zero 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).
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.
LUKS2 is a new version of the header format that allows additional extensions like different PBKDF algorithms or authenticated encryption.
You can format the device with a LUKS2 header if you specify *--type luks2* in the *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.
Each passphrase, also called a *key* in this document, is associated with one of 8 keyslots.
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.
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:
=== FORMAT
*luksFormat <device> [<key file>]*
Initializes a LUKS partition and sets the initial passphrase (for key-slot 0). +
Initializes a LUKS partition and sets the initial passphrase (for keyslot 0). +
See *cryptsetup-luksFormat*(8).
=== OPEN
@@ -156,9 +156,9 @@ Converts an existing LUKS2 keyslot to new PBKDF parameters. +
See *cryptsetup-luksConvertKey*(8).
=== KILL SLOT
*luksKillSlot <device> <key slot number>*
*luksKillSlot <device> <number>*
Wipe the key-slot number <key slot> from the LUKS device. +
Wipe the keyslot with the <number> from the LUKS device. +
See *cryptsetup-luksKillSlot*(8).
=== ERASE
@@ -218,7 +218,7 @@ See *cryptsetup-config*(8).
== loop-AES EXTENSION
Cryptsetup supports mapping loop-AES encrypted partition using a compatibility mode.
Cryptsetup supports mapping a loop-AES encrypted partition using a compatibility mode.
=== OPEN
*open --type loopaes <device> <name> --key-file <keyfile>* +
@@ -231,19 +231,19 @@ See also section 7 of the FAQ and http://loop-aes.sourceforge.net[loop-AES] for
== 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 partitions using a native Linux kernel API.
Header formatting and TCRYPT header change are not supported; cryptsetup never changes the 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 the kernel userspace crypto API to be available (introduced in Linux kernel 2.6.38).
If you are configuring the 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 the TCRYPT header is encrypted, you must always provide a 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 a 64-bit encryption block (namely, Blowfish in LRW mode is not recognized; this is a limitation of the kernel crypto API).
VeraCrypt is extension of TrueCrypt header with increased iteration count so unlocking can take quite a lot of time.
VeraCrypt is an extension of TrueCrypt with an 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.
@@ -254,15 +254,15 @@ If you need to disable VeraCrypt device support, use --disable-veracrypt option.
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.
To map the 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 a 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 the 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.
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>* +
@@ -279,25 +279,25 @@ 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.
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 partitions using a native Linux kernel API.
Header formatting and BITLK header changes are not supported; cryptsetup never changes the BITLK header on-device.
BITLK extension requires kernel userspace crypto API to be available (for details see TCRYPT section).
BITLK extension requires the kernel userspace crypto API to be available (for details, see the 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 the legacy header used in Windows Vista systems and partially decrypted BitLocker devices.
Activation of legacy devices encrypted in CBC mode requires at least a Linux kernel version 5.3, and for devices using the Elephant diffuser, kernel 5.6.
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, a recovery passphrase, or a startup key must be provided.
Additionally unlocking using volume key is supported.
Additionally, unlocking using the 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).
The key must be decrypted and without the header (only 128/256/512 bits of key data depending on the used cipher and mode).
Other unlocking methods (TPM, SmartCard) are not supported.
@@ -314,7 +314,7 @@ 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
@@ -325,7 +325,7 @@ It does NOT support the new version of FileVault based on the APFS filesystem us
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 the kernel userspace crypto API to be available (for details, see the TCRYPT section) and a kernel driver for the HFS+ (hfsplus) filesystem.
Cryptsetup should recognize the basic configuration for portable drives.
@@ -344,22 +344,22 @@ 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).
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.
*WARNING:* This support is new and experimental, and requires at least kernel v6.4.
Resizing devices is not supported.
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.
Opening, closing and enrolling tokens work 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.
Other than the usual passphrase, an admin password will have to be specified when formatting the drive's first partition, and will have to be re-supplied when formatting any other partition until a factory reset is performed.
=== ERASE
*erase <device>*
@@ -368,9 +368,9 @@ 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.
*NOTE*: PSID must be entered without 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 run on, if any, and regardless of any LUKS2 header backup.
== MISCELLANEOUS ACTIONS
@@ -384,13 +384,13 @@ See *cryptsetup-repair*(8).
=== BENCHMARK
*benchmark <options>*
Benchmarks ciphers and KDF (key derivation function). +
Benchmarks, ciphers and KDF (key derivation function). +
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.
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
@@ -402,40 +402,40 @@ 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.
See the Cryptsetup FAQ for advice on how to back up 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.
Keyboard settings can also be changed, 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 a 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.
*LUKS header:* If the header of a LUKS volume gets damaged, all data is permanently lost unless you have a header backup.
If a keyslot is damaged, it can only be restored from a header backup or if another active keyslot with a 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.
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 the header and keyslot 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.
*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.
For a quick removal of filesystem signatures, use *wipefs*(8).
Take care though that this may not remove everything.
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.
For a full wipe, overwrite the whole partition before creating a container.
If you do not know how to do that, the cryptsetup FAQ describes several options.
== EXAMPLES
Example 1: Create LUKS 2 container on block device /dev/sdX.::
sudo cryptsetup --type luks2 luksFormat /dev/sdX
Example 2: Add an additional passphrase to key slot 5.::
Example 2: Add an additional passphrase to keyslot 5.::
sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX
Example 3: Create LUKS header backup and save it to file.::
Example 3: Create LUKS header backup and save it to a file.::
sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file
/var/tmp/NameOfBackupFile
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.
Example 5: Erase all key slots on /dev/sdX.::
*WARNING: The command in example 5 will erase all keyslots.*::
You cannot use your LUKS container afterward anymore unless you have a backup to restore.
Example 5: Erase all keyslots on /dev/sdX.::
sudo cryptsetup erase /dev/sdX
Example 6: Restore LUKS header from backup file.::
sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file
@@ -455,20 +455,20 @@ 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'.
*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.
The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --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.
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.
If "plain" is used as an 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.
@@ -478,7 +478,7 @@ No warning will be given if the amount of data read from stdin is less than the
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.
The maximum input size is defined by the same compiled-in default as the maximum key file size and can be overwritten using the --keyfile-size option.
=== Passphrase processing for LUKS
@@ -493,13 +493,13 @@ If --keyfile-size is given, it is ignored.
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.
*Passphrase processing*: Whenever a passphrase is added to a LUKS header (luksAddKey, luksFormat), the user may specify how much 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 the open command 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.
On a slow device, it may be advisable to increase the iteration time using the --iter-time option to obtain a higher iteration count.
This does slow down all later luksOpen operations accordingly.
=== Incoherent behavior for invalid passphrases/keys
@@ -513,7 +513,7 @@ If the given passphrase is wrong, the device mapped by plain dm-crypt will essen
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.
You might need to load additional kernel crypto modules 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.
@@ -522,56 +522,56 @@ For other crypto backends, some algorithms may be missing.
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.
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 (RNGs) used in cryptsetup are always the kernel RNGs without any modifications or additions to the data stream produced.
There are two types of randomness cryptsetup/LUKS needs.
There are two types of randomness that 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.
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.
See *urandom*(4) for more information.
=== Authenticated disk encryption (EXPERIMENTAL)
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 (the plaintext sector is the same size as a ciphertext sector) and can provide only confidentiality protection, 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 the 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.
If you configure a LUKS2 device with data integrity protection, there will be an underlying dm-integrity device, which provides additional per-sector metadata space and data journal protection to ensure atomicity of data and metadata updates.
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 a 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).
Some integrity modes require two independent keys (a key for encryption and 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 only some modes are available now.
Note that very few authenticated encryption algorithms are suitable for disk encryption.
You also cannot use CRC32 or 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.
This mode requires a 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.
@@ -579,19 +579,19 @@ 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.
The LUKS2 on-disk metadata is updated in several steps, and to achieve a proper atomic update, there is a locking mechanism.
For an image in a file, the code uses the *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.
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]. +
Cryptsetup was 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]. +
Man page extensions by mailto:gmazyland@gmail.com[Milan Broz]. +
Man page rewrite and extension by mailto:arno@wagner.name[Arno Wagner].

85
man/integritysetup.8.adoc
View File

@@ -6,7 +6,7 @@
== NAME
integritysetup - manage dm-integrity (block level integrity) volumes
integritysetup - manage dm-integrity (block-level integrity) volumes
== SYNOPSIS
@@ -16,9 +16,9 @@ integritysetup - manage dm-integrity (block level integrity) volumes
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.
The device-mapper integrity target provides read-write transparent integrity checking for block devices.
The dm-integrity target emulates an additional data integrity field per sector.
You can use this additional field directly with the integritysetup utility, or indirectly (for authenticated encryption) through cryptsetup.
== BASIC ACTIONS
@@ -58,18 +58,18 @@ Reports status for the active integrity mapping <name>.
=== DUMP
*dump <device>*
Reports parameters from on-disk stored superblock.
Report parameters from the on-disk stored superblock.
=== RESIZE
*resize <name>*
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.
If --size (in 512-byte sectors) or --device-size is 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 has been possible since the Linux kernel version 5.7; shrinking should work on older kernels, too.
*<options>* can be [--size, --device-size, --wipe].
@@ -85,48 +85,49 @@ 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 don'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.
The number of 512-byte sectors per bitmap bit must be a 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 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 the *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>.
The <device> will then contain calculated integrity tags and a 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 recalculate integrity tags automatically.
*--debug*::
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 the *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).
The integrity algorithm can be CRC (crc32c/crc32), a non-cryptographic hash function (xxhash64) or a hash function (sha1, sha256).
+
For HMAC (hmac-sha256) you have also to specify an integrity key and its size.
For HMAC (hmac-sha256), you must 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.
Use alternate bitmap mode (available since Linux kernel 5.2), where dm-integrity uses a 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.
The bitmap mode is faster than the journal mode because we don't have to write the data twice.
However, 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.
Store integrity tags in 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.
@@ -143,17 +144,17 @@ The size of the data integrity key.
Maximum is 4096 bytes.
*--integrity-no-journal*, *-D*::
Disable journal for integrity device.
Disable the journal for the 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.
Automatically recalculate integrity tags in the 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.
Note, it does not change the tag length.
This option is available since the Linux kernel version 5.13.
*--integrity-recovery-mode*, *-R*::
@@ -164,11 +165,11 @@ 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.
The journal is written when this time passes (and no explicit flush operation was issued).
*--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 the 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.
@@ -181,7 +182,7 @@ The size of the journal encryption key.
Maximum is 4096 bytes.
*--journal-integrity* _algorithm_::
Integrity algorithm for journal area.
Integrity algorithm for the journal area.
See --integrity option for detailed specification.
*--journal-integrity-key-file* _file_::
@@ -195,20 +196,20 @@ Maximum is 4096 bytes.
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 percent.
When the journal size exceeds this watermark, the journal flush will be started.
*--no-wipe*::
Do not wipe the device after format.
Do not wipe the device after formatting.
A device that is not initially wiped will contain invalid checksums.
*--progress-frequency* _seconds_::
Print separate line every <seconds> with wipe progress.
Print a 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, which is suitable mostly for machine processing.
It prints a separate line every half second (or based on --progress-frequency value).
The JSON output looks as follows during wipe progress (except it's a compact single line):
+
....
{
@@ -221,15 +222,15 @@ The JSON output looks as follows during wipe progress (except it's compact singl
}
....
+
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 the need for full 64-bit 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 the 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 than the output size of the hash function; in that case, only part of the hash will be stored.
*--usage*::
Show short option help.
@@ -241,13 +242,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 resizing to a bigger size.
If this flag is not set, checksums will be calculated for previously stored data 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 a specific old kernel.
*--integrity-legacy-padding*::
Use inefficient legacy padding.
@@ -267,7 +268,7 @@ Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4*
== 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 the dm-integrity kernel target.
== EXAMPLES
@@ -293,7 +294,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 is available on the https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[DMIntegrity] page.
== AUTHORS

114
man/veritysetup.8.adoc
View File

@@ -6,7 +6,7 @@
== NAME
veritysetup - manage dm-verity (block level verification) volumes
veritysetup - manage dm-verity (block-level verification) volumes
== SYNOPSIS
@@ -27,14 +27,14 @@ 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 the 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.
You need to provide the 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 a block device or a file image.
If the hash device path doesn't exist, it will be created as a file.
*<options>* can be [--hash, --no-superblock, --format, --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid, --root-hash-file].
@@ -51,27 +51,27 @@ 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].
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 the command line parameter.
Expects hex-encoded text, without a terminating newline.
If option --no-superblock is used, you have to use as the same options as in initial format operation.
If --no-superblock is used, you must use the same options as in the 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 using 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 the command line parameter.
Expects hex-encoded text, without a 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 --no-superblock is used, you must use the same options as in the initial format operation.
=== CLOSE
*close <name>* +
@@ -89,7 +89,7 @@ Reports status for the active verity mapping <name>.
=== DUMP
*dump <hash_device>*
Reports parameters of verity device from on-disk stored superblock.
Report parameters of the verity device from the on-disk stored superblock.
*<options>* can be [--hash-offset].
@@ -98,28 +98,28 @@ 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.
Cancels a previously configured deferred device removal in the *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 the kernel to verify blocks only once 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.
*--data-blocks* _blocks_::
Size of data device used in verification.
Size of the 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.)
Maximum is the page size used by the kernel.
*--debug*::
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 the *close* command until the last user closes it.
*--error-as-corruption*::
Handle device I/O errors the same as data corruption.
@@ -129,94 +129,94 @@ This option must be combined with --restart-on-corruption or --panic-on-corrupti
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 a block device or a file image.
For format, if the FEC device path doesn't exist, it will be created as a file.
+
Block sizes for data and hash devices must match.
Also, if the verity data_device is encrypted the fec_device should be too.
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 as the hash tree (additional space after the hash area).
The size of this optional additional area protected by FEC is calculated from image sizes, so you must 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 entire image after the hash area.
+
If hash and FEC device is in the image, metadata ends on the FEC area offset.
The metadata ends on the FEC area offset if the hash and FEC device are in the image.
*--fec-offset* _bytes_::
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.
This equals 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).
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.
Format type 0 is the original Chrome OS version.
Format type 1 is the current version.
*--hash* _hash_::
Hash algorithm for dm-verity.
For default see --help option.
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.)
Maximum is the page size used by the kernel.
*--hash-offset* _bytes_::
Offset of hash area/superblock on hash_device.
Value must be aligned to disk sector offset.
Value must be aligned with the 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 a data integrity problem (data corruption) is detected.
+
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, the kernel fails the I/O operation with an 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 a way to avoid restart loops.)
+
*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 the kernel not to verify blocks 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.
*--no-superblock*::
Create or use dm-verity without permanent on-disk superblock.
Create or use dm-verity without a permanent on-disk superblock.
*--root-hash-file* _file_*::
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.
A path to the root hash signature file used to verify the root hash (in kernel).
This feature requires a Linux kernel version 5.4 or more recent.
*--salt=hex string*::
Salt used for format or verification.
Salt used for formatting 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 the data device to be used in shared mode.
The data device is not checked for exclusive access before the device activation and may be mapped in multiple verity mappings.
*--usage*::
Show short option help.
*--use-tasklets*::
Try to use kernel tasklets in dm-verity driver for performance reasons.
Try to use kernel tasklets in the 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 the format command instead of generating a 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.
@@ -234,23 +234,23 @@ Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4*
*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 a 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 stores the root hash as hex-encoded text in <path>.
*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.
Hash offset must be greater than the number of blocks in the data area.
*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.
The <root_hash> was calculated in the format command.
*veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash>*
@@ -259,15 +259,15 @@ Verifies device without activation (in userspace).
*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.
Root hash is passed via file rather than inline.
*veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device>*
Calculates and stores verification and encoding data for data_device.
Calculates and stores verification and encoding data for the 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 on the https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page.
== AUTHORS