From 349912fec260c5cb9484ca7408c255dab16d6fbe Mon Sep 17 00:00:00 2001 From: Milan Broz Date: Wed, 23 Jul 2025 15:19:11 +0200 Subject: [PATCH] man: Do not use *NOTE*, it is just a normal description. --- man/common_options.adoc | 48 +++++++++++++++----------------- man/cryptsetup-luksAddKey.8.adoc | 2 +- man/cryptsetup-reencrypt.8.adoc | 4 +-- man/cryptsetup.8.adoc | 8 +++--- man/integritysetup.8.adoc | 6 ++-- 5 files changed, 33 insertions(+), 35 deletions(-) diff --git a/man/common_options.adoc b/man/common_options.adoc index 8d8fa963..3c315798 100644 --- a/man/common_options.adoc +++ b/man/common_options.adoc @@ -64,10 +64,10 @@ Set the cipher specification string for the data segment only. *LUKS1*: Set the cipher specification string for the data segment and keyslots. + -*NOTE*: In encrypt mode, if cipher specification is omitted, the default cipher is applied. -In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain in use. -Unless the existing cipher was "cipher_null". -In that case, the default cipher would be applied as in encrypt mode. +The default cipher is applied if the cipher specification is omitted in encrypt mode. ++ +In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain. +The only exception is if the cipher is "cipher_null", then the default cipher is used. endif::[] ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[] + @@ -117,7 +117,6 @@ It means that only the specified area (from the start of the device to the speci *LUKS2*: When used together with --reduce-device-size, only the initial _size_ value (--device-size parameter) of data is shifted backwards while being encrypted. + -*NOTE*: The sum of --device-size and --reduce-device-size values must not exceed the real device size. + *WARNING:* This is a destructive operation. @@ -151,7 +150,7 @@ Disable lock protection for metadata on disk. This option is valid only for LUKS2 and is ignored for other formats. + ifdef::ACTION_REENCRYPT[] -*NOTE:* With locking disabled, LUKS2 images in files can be fully (re)encrypted offline without the need for superuser privileges provided that the used block ciphers are available in the crypto backend. +With locking disabled, LUKS2 images in files can be fully (re)encrypted offline without the need for superuser privileges provided that the used block ciphers are available in the crypto backend. + endif::[] *WARNING:* Do not use this option unless you run cryptsetup in a restricted environment where locking is impossible to perform (where /run directory cannot be used). @@ -191,7 +190,7 @@ ifdef::ACTION_REENCRYPT[] Enforce initialization of reencryption operation with additional --volume-key-file, --new-volume-key-file, --volume-key-keyring or --new-volume-key-keyring parameters. It would result in the deletion of all remaining LUKS2 keyslots containing the volume key. + -*NOTE:* LUKS2 keyslot with new volume key may be added after the reencryption operation is finished. +LUKS2 keyslot with the new volume key may be added after the reencryption operation is finished. See *cryptsetup-luksAddKey*(8) command. + *WARNING:* Use with extreme caution! @@ -236,7 +235,7 @@ ifdef::ACTION_REENCRYPT[] *LUKS1:* Specifies the hash used in the LUKS1 key setup scheme and volume key digest. + -*NOTE*: If this parameter is not specified, the default hash algorithm is always used for a new LUKS1 device header. +If this parameter is not specified, the default hash algorithm is always used for a new LUKS1 device header. + *LUKS2:* Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf). endif::[] @@ -325,7 +324,7 @@ After providing the correct PSID via interactive prompt or via --key-file parame PSID is usually printed on the OPAL drive label (either directly or as a QR code). PSID must be entered without any dashes, spaces or underscores. + -*NOTE*: PSID should be treated as sensitive information as it allows anyone with remote access to the OPAL drive to destroy data even if the device is locked. +PSID should be treated as sensitive information as it allows anyone with remote access to the OPAL drive to destroy data even if the device is locked. Be sure you do not leak PSID through transparent packaging during transport or images of the drive posted online. endif::[] @@ -335,7 +334,7 @@ Format LUKS2 device with HW based encryption configured on SED OPAL locking rang LUKS2 format only manages the locking range unlock key. This option enables HW-based data encryption managed by the SED OPAL drive only. + -*NOTE*: Please note that with OPAL-only (--hw-opal-only) encryption, the configured OPAL administrator PIN (passphrase) allows unlocking all configured locking ranges without LUKS keyslot decryption (without knowledge of LUKS passphrase). +Please note that with OPAL-only (--hw-opal-only) encryption, the configured OPAL administrator PIN (passphrase) allows unlocking all configured locking ranges without LUKS keyslot decryption (without knowledge of LUKS passphrase). Because of many observed problems with compatibility, cryptsetup currently DOES NOT use OPAL single-user mode, which would allow such decoupling of OPAL admin PIN access. endif::[] @@ -393,7 +392,9 @@ ifdef::ACTION_LUKSFORMAT[] Skip wiping of device authentication (integrity) tags. If you skip this step, sectors will report an invalid integrity tag until an application writes to the sector. + -*NOTE:* Even some writes to the device can fail if the write is not aligned to the page size and the page cache initiates a read of a sector with an invalid integrity tag. +Skipping this step could also cause write failures due to IO operation alignments. +For example, kernel page cache can request a read of a full page that fails due to an uninitialized integrity tag. +It is usually a bug in the application that tries to read data that was not written before. endif::[] ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[] @@ -412,7 +413,7 @@ ifdef::ACTION_OPEN[] Count Initialization Vector (IV) in larger sector size (if set) instead of 512-byte sectors. This option can be used only with the _plain_ device type. + -*NOTE:* This option does not have any performance or security impact; use it only for accessing incompatible existing disk images from other systems that require this option. +This option does not have any performance or security impact; use it only for accessing incompatible existing disk images from other systems that require this option. endif::[] ifdef::ACTION_TOKEN[] @@ -455,7 +456,7 @@ endif::[] + endif::[] ifdef::ACTION_OPEN[] -*NOTE:* With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt. +With _plain_ device type, the passphrase obtained via --key-file option is passed directly in dm-crypt. Unlike the interactive mode (stdin), where the digest of the passphrase is passed in dm-crypt instead. + endif::[] @@ -536,9 +537,9 @@ ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKS ifdef::ACTION_LUKSADDKEY[] When used together with the parameter --new-key-slot, this option allows you to specify which keyslot is selected for unlocking the volume key. + -*NOTE:* This option is ignored if the existing volume key gets unlocked via LUKS2 token (--token-id, --token-type or --token-only parameters) or when volume key is provided directly via --volume-key-file parameter. +This option is ignored if the existing volume key gets unlocked via LUKS2 token (--token-id, --token-type or --token-only parameters) or when volume key is provided directly via --volume-key-file parameter. + -*NOTE:* To maintain backward compatibility, without --new-key-slot parameter, this option allows you to specify which keyslot is selected for the new key. +To maintain backward compatibility, without --new-key-slot parameter, this option allows you to specify which keyslot is selected for the new key. endif::[] ifndef::ACTION_OPEN,ACTION_LUKSADDKEY[] For LUKS operations that add key material, this option allows you to specify which keyslot is selected for the new key. @@ -657,8 +658,6 @@ ifdef::ACTION_LUKSADDKEY[] *--new-key-slot* _<0-N>_:: This option allows you to specify which keyslot is selected for the new key. + -*NOTE:* When used this option affects --key-slot option. -+ The maximum number of keyslots depends on the LUKS version. LUKS1 can have up to 8 keyslots. LUKS2 can have up to 32 keyslots based on keyslot area size and key size, but a valid keyslot ID can always be between 0 and 31 for LUKS2. @@ -732,7 +731,7 @@ The parallel cost --pbkdf-parallel is constant and is checked against available + You can see all PBKDF parameters for a particular LUKS2 keyslot with the *cryptsetup-luksDump*(8) command. + -*NOTE:* If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. +If you do not want to use benchmark and want to specify all parameters directly, use --pbkdf-force-iterations with --pbkdf-memory and --pbkdf-parallel. This will override the values without benchmarking. Note it can cause extremely long unlocking time or cause out-of-memory conditions with unconditional process termination. Use only in specific cases, for example, if you know that the formatted device will be used on some small embedded system. @@ -772,7 +771,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[] Set dm-crypt workqueues and the writer thread to high priority. This improves throughput and latency of dm-crypt while degrading the general responsiveness of the system. + -*NOTE:* This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. +This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. Needs kernel 6.10 or later. endif::[] @@ -780,7 +779,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[] *--perf-no_read_workqueue*, *--perf-no_write_workqueue*:: Bypass dm-crypt internal workqueue and process read or write requests synchronously. + -*NOTE:* These options are available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. +These options are available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. Needs kernel 5.9 or later. endif::[] @@ -789,7 +788,7 @@ ifdef::ACTION_REFRESH,ACTION_OPEN[] Perform encryption using the same CPU on which that IO was submitted. The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs. + -*NOTE:* This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. +This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. endif::[] ifdef::ACTION_REFRESH,ACTION_OPEN[] @@ -798,7 +797,7 @@ Disable offloading writes to a separate thread after encryption. There are some situations where offloading write bios from the encryption threads to a single thread degrades performance significantly. The default is to offload write bios to the same thread. + -*NOTE:* This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. +This option is available only for low-level dm-crypt performance tuning, use only if you need a change to the default dm-crypt behaviour. endif::[] ifdef::ACTION_OPEN,ACTION_REFRESH[] @@ -871,7 +870,6 @@ The former first data segment is replaced with LUKS2 header (half the _size_ val + The recommended minimum size is twice the default LUKS2 header size (--reduce-device-size 32M) for encryption mode. + -*NOTE*: The sum of --device-size and --reduce-device-size values must not exceed the real device size. + *LUKS1*: @@ -956,7 +954,7 @@ ifdef::ACTION_OPEN[] *--serialize-memory-hard-pbkdf*:: Use a global lock to serialize unlocking of keyslots using memory-hard PBKDF. + -*NOTE:* This is a workaround for a specific situation when multiple devices are activated in parallel, and the system, instead of reporting out of memory, starts unconditionally stop processes using the out-of-memory killer. +This is a workaround for a specific situation when multiple devices are activated in parallel, and the system, instead of reporting out of memory, starts unconditionally stop processes using the out-of-memory killer. + *DO NOT USE* this switch until you are implementing the boot environment with parallel devices activation! endif::[] @@ -1067,7 +1065,7 @@ endif::[] ifdef::ACTION_LUKSADDKEY[] Use only LUKS2 tokens to unlock the existing volume key. + -*NOTE*: To create a new keyslot using the passphrase provided by a token, use --new-token-id parameter. +To create a new keyslot using the passphrase provided by a token, use --new-token-id parameter. endif::[] endif::[] diff --git a/man/cryptsetup-luksAddKey.8.adoc b/man/cryptsetup-luksAddKey.8.adoc index 2837f8c1..b0bc1d04 100644 --- a/man/cryptsetup-luksAddKey.8.adoc +++ b/man/cryptsetup-luksAddKey.8.adoc @@ -35,7 +35,7 @@ include::man/common_options.adoc[] == EXAMPLES -*NOTE*: The interactive passphrase prompt is always the default method when not specified otherwise. +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 passphrases: diff --git a/man/cryptsetup-reencrypt.8.adoc b/man/cryptsetup-reencrypt.8.adoc index ac8a64ff..4f4bfc65 100644 --- a/man/cryptsetup-reencrypt.8.adoc +++ b/man/cryptsetup-reencrypt.8.adoc @@ -39,7 +39,7 @@ The same applies to the SIGTERM signal (i.e., issued by systemd during system sh 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. +Note that for encrypt and decrypt mode, the whole device must be treated as unencrypted -- there are no guarantees of confidentiality as part of the device contains plaintext. *ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS ACTION ON LUKS DEVICE.* @@ -111,7 +111,7 @@ include::man/common_options.adoc[] == EXAMPLES -*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is default. +You may drop *--type luks2* option as long as LUKS2 format is default. === LUKS2 ENCRYPTION EXAMPLES diff --git a/man/cryptsetup.8.adoc b/man/cryptsetup.8.adoc index f6fbb1d7..2717cb2e 100644 --- a/man/cryptsetup.8.adoc +++ b/man/cryptsetup.8.adoc @@ -257,7 +257,7 @@ Please refer to https://veracrypt.io/en/Personal%20Iterations%20Multiplier%20(PI If you need to disable VeraCrypt device support, use --disable-veracrypt option. -*NOTE:* Activation with *tcryptOpen* is supported only for cipher chains using LRW or XTS encryption modes. +Activation with *tcryptOpen* is supported only for cipher chains using LRW or XTS encryption modes. The *tcryptDump* command should work for all recognized TCRYPT devices and doesn't require superuser privilege. @@ -268,7 +268,7 @@ To use a hidden header (and map hidden device, if available), use --tcrypt-hidde 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. +There is no protection for a hidden volume if the outer volume is mounted. The reason is that if there were any protection, it would require some metadata describing what to protect in the outer volume, and the hidden volume would become detectable. === OPEN @@ -327,7 +327,7 @@ Please note that cryptsetup does not use any Windows BitLocker code; please repo Cryptsetup supports the mapping of FileVault2 (FileVault2 full-disk encryption) by Apple for the macOS operating system using a native Linux kernel API. -*NOTE:* Cryptsetup supports only FileVault2 based on Core Storage and HFS+ filesystem (introduced in MacOS X 10.7 Lion). +Cryptsetup supports only FileVault2 based on Core Storage and HFS+ filesystem (introduced in MacOS X 10.7 Lion). It does NOT support the new version of FileVault based on the APFS filesystem used in recent macOS versions. Header formatting and FVAULT2 header changes are not supported; cryptsetup never changes the FVAULT2 header on-device. @@ -376,7 +376,7 @@ 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 dashes, spaces or underscores. +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 run on, if any, and regardless of any LUKS2 header backup. diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc index f69546eb..f7fc8677 100644 --- a/man/integritysetup.8.adoc +++ b/man/integritysetup.8.adoc @@ -104,7 +104,7 @@ Removes a previously configured deferred device removal in the *close* command. Specify a separate data device that contains existing data. The will then contain calculated integrity tags and a journal for data on . + -*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. +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. @@ -172,7 +172,7 @@ The journal is written when this time passes (and no explicit flush operation wa 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. +The journal encryption options are only intended for testing. Using journal encryption does not make sense without encryption of the data. *--journal-crypt-key-file* _file_:: @@ -231,7 +231,7 @@ 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 the authentication tag). + -*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. +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.