Merging upstream version 2:2.7.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

17 files changed, 460 insertions, 37 deletions

diff --git a/man/Makemodule.am b/man/Makemodule.am
index 41e21da..03beb7a 100644
--- a/man/Makemodule.am
+++ b/man/Makemodule.am
@@ -107,6 +107,8 @@ if SSHPLUGIN_TOKEN
 MANPAGES += $(SSHPLUGIN_MANPAGES)
 endif
 
+EXTRA_DIST += man/meson_dist_convert.sh
+
 if ENABLE_ASCIIDOC
 EXTRA_DIST += $(MANPAGES_ALL)
 man8_MANS += $(MANPAGES) $(MANLINKS)
diff --git a/man/common_options.adoc b/man/common_options.adoc
index 56a6e29..497d7fd 100644
--- a/man/common_options.adoc
+++ b/man/common_options.adoc
@@ -131,8 +131,14 @@ ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY[]
 The passphrase supplied via --key-file is always the passphrase for existing
 keyslot requested by the command.
 +
+ifdef::ACTION_LUKSADDKEY[]
 If you want to set a new passphrase via key file, you have to use a
 positional argument or parameter --new-keyfile.
+endif::[]
+ifdef::ACTION_LUKSCHANGEKEY[]
+If you want to set a new passphrase via key file, you have to use a
+positional argument.
+endif::[]
 +
 endif::[]
 ifdef::ACTION_OPEN[]
@@ -153,6 +159,16 @@ If this option is not used, cryptsetup will ask for all active keyslot
 passphrases.
 endif::[]
 endif::[]
+ifdef::ACTION_ERASE[]
+*--key-file, -d* _name_ *(LUKS2 with HW OPAL only)*::
+
+Read the Admin PIN or PSID (with --hw-opal-factory-reset) from file
+depending on options used.
++
+If the name given is "-", then the secret will be read from stdin.
+In this case, reading will not stop at newline characters.
++
+endif::[]
 
 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[]
 *--keyfile-offset* _value_::
@@ -229,6 +245,19 @@ partially predictable volume key which will compromise security.
 endif::[]
 endif::[]
 
+ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[]
+*--volume-key-keyring* _<key description>_::
+Use a volume key stored in a keyring.
+This allows one to open _luks_ and device types without giving a passphrase.
+The key and associated type has to be readable from userspace so that volume
+key digest may be verified in before activation.
++
+The _<key description>_ uses keyctl-compatible syntax. This can either be a
+numeric key ID or a string name in the format _%<key type>:<key name>_. See
+also *KEY IDENTIFIERS* section of *keyctl*(1). When no _%<key type>:_ prefix
+is specified we assume the key type is _user_ (default type).
+endif::[]
+
 ifdef::ACTION_LUKSDUMP[]
 *--dump-json-metadata*::
 For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header
@@ -476,7 +505,8 @@ You can see all PBKDF parameters for particular LUKS2 keyslot with
 *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_. This will override the values
-without benchmarking. Note it can cause extremely long unlocking time.
+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.
 +
@@ -670,7 +700,7 @@ endif::[]
 
 ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[]
 *--header <device or file storing the LUKS header>*::
-ifndef::ACTION_OPEN[]
+ifndef::ACTION_OPEN,ACTION_ERASE[]
 Use a detached (separated) metadata device or file where the LUKS
 header is stored. This option allows one to store ciphertext and LUKS
 header on different devices.
@@ -693,7 +723,7 @@ FAQ for header size calculation.
 The --align-payload option is taken as absolute sector alignment on ciphertext
 device and can be zero.
 endif::[]
-ifndef::ACTION_LUKSFORMAT,ACTION_OPEN[]
+ifndef::ACTION_LUKSFORMAT,ACTION_OPEN,ACTION_ERASE[]
 For commands that change the LUKS header (e.g. _luksAddKey_),
 specify the device or file with the LUKS header directly as the LUKS
 device.
@@ -713,6 +743,9 @@ decryption operation continues as if the ordinary detached header was passed.
 *WARNING:* Never put exported header file in a filesystem on top of device
 you are about to decrypt! It would cause a deadlock.
 endif::[]
+ifdef::ACTION_ERASE[]
+Use to specify detached LUKS2 header when erasing HW OPAL enabled data device.
+endif::[]
 endif::[]
 
 ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[]
@@ -720,6 +753,19 @@ ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[]
 Specify file with header backup file.
 endif::[]
 
+ifdef::ACTION_LUKSFORMAT[]
+*--hw-opal*::
+Format LUKS2 device with dm-crypt encryption stacked on top HW based encryption configured
+on SED OPAL locking range. This option enables both SW and HW based data encryption.
+endif::[]
+
+ifdef::ACTION_LUKSFORMAT[]
+*--hw-opal-only*::
+Format LUKS2 device with HW based encryption configured on SED OPAL locking range only. LUKS2
+format only manages locking range unlock key. This option enables HW based data encryption managed
+by SED OPAL drive only.
+endif::[]
+
 ifdef::ACTION_REENCRYPT[]
 *--force-offline-reencrypt (LUKS2 only)*::
 Bypass active device auto-detection and enforce offline reencryption.
@@ -757,6 +803,11 @@ Removes a previously configured deferred device removal in _close_
 command.
 endif::[]
 
+ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
+*--disable-blkid*::
+Disable use of blkid library for checking and wiping on-disk signatures.
+endif::[]
+
 ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[]
 *--disable-external-tokens*::
 Disable loading of plugins for external LUKS2 tokens.
@@ -789,6 +840,26 @@ ifdef::ACTION_TOKEN[]
 Set key description in keyring for use with _token_ command.
 endif::[]
 
+ifdef::ACTION_OPEN,ACTION_LUKSRESUME[]
+*--link-vk-to-keyring* _<keyring_description>::<key_description>_::
+Link volume key in a keyring with specified key name. The volume key is linked only
+if requested action is successfully finished.
++
+_<keyring_description>_ string has to contain existing kernel keyring
+description. The keyring name may be optionally prefixed with "%:" or "%keyring:" type descriptions.
+Or, the keyring may also be specified directly by numeric key id. Also special keyring notations
+starting with "@" may be used to select existing predefined kernel keyrings.
++
+The string "::" is delimiter used to separate keyring description and key description.
++
+_<key_description>_ part describes key type and key name of volume key linked in the keyring
+described in _<keyring_description>_. The type may be specified by adding "%<type_name>:" prefix in front of
+key name. If type is missing default _user_ type is applied. If the key of same name and same type already exists (already linked in the keyring)
+it will get replaced in the process.
++
+See also *KEY IDENTIFIERS* section of *keyctl*(1).
+endif::[]
+
 ifdef::ACTION_CONFIG[]
 *--priority <normal|prefer|ignore>*::
 Set a priority for LUKS2 keyslot. The _prefer_ priority marked slots
@@ -800,7 +871,7 @@ endif::[]
 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKEY[]
 *--token-id*::
 ifndef::ACTION_TOKEN,ACTION_LUKSADDKEY[]
-Specify what token to use and allow token PIN prompt to take precedence over interative
+Specify what token to use and allow token PIN prompt to take precedence over interactive
 keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN)
 will be checked before proceeding further with passphrase prompt.
 endif::[]
@@ -1163,6 +1234,12 @@ Enlarge data offset to specified value by shrinking device size.
 You cannot shrink device more than by 64 MiB (131072 sectors).
 endif::[]
 
+ifdef::ACTION_RESIZE,ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN[]
+*--external-tokens-path* _absolute_path_::
+Override system directory path where cryptsetup searches for external token
+handlers (or token plugins). It must be absolute path (starting with '/' character).
+endif::[]
+
 ifdef::COMMON_OPTIONS[]
 *--batch-mode, -q*::
 Suppresses all confirmation questions. Use with care!
diff --git a/man/cryptsetup-erase.8.adoc b/man/cryptsetup-erase.8.adoc
index 97a13aa..6ad7eca 100644
--- a/man/cryptsetup-erase.8.adoc
+++ b/man/cryptsetup-erase.8.adoc
@@ -18,11 +18,17 @@ cryptsetup-erase, cryptsetup-luksErase - erase all keyslots
 == DESCRIPTION
 
 Erase all keyslots and make the LUKS container permanently inaccessible.
-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.
 
-*<options>* can be [--header, --disable-locks].
+*WARNING:* with *--hw-opal-factory-reset* ALL data is lost on the device,
+regardless of the partition it is ran on, if any, and regardless of any LUKS2
+header backup, and does not require a valid LUKS2 header to be present on the
+device to run.
+
+*<options>* can be [--header, --disable-locks, --hw-opal-factory-reset, --key-file].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]
diff --git a/man/cryptsetup-luksAddKey.8.adoc b/man/cryptsetup-luksAddKey.8.adoc
index 9686a1d..306ef64 100644
--- a/man/cryptsetup-luksAddKey.8.adoc
+++ b/man/cryptsetup-luksAddKey.8.adoc
@@ -19,9 +19,9 @@ 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). 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.
+(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
@@ -34,11 +34,11 @@ algorithm is always the same for all keyslots.
 
 *<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
 --new-keyfile, --new-keyfile-offset, --new-keyfile-size, --key-slot,
---new-key-slot, --volume-key-file, --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].
+--new-key-slot, --volume-key-file, --volume-key-keyring, --force-password,
+--hash, --header, --disable-locks, --iter-time, --pbkdf,
+--pbkdf-force-iterations, --pbkdf-memory, --pbkdf-parallel, --unbound, --type,
+--keyslot-cipher, --keyslot-key-size, --key-size, --timeout, --token-id,
+--token-type, --token-only, --new-token-id, --verify-passphrase, --external-tokens-path].
 
 include::man/common_options.adoc[]
 
diff --git a/man/cryptsetup-luksChangeKey.8.adoc b/man/cryptsetup-luksChangeKey.8.adoc
index 7dd5f3b..23376c0 100644
--- a/man/cryptsetup-luksChangeKey.8.adoc
+++ b/man/cryptsetup-luksChangeKey.8.adoc
@@ -30,7 +30,9 @@ 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.
+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.
 
 *NOTE:* some parameters are effective only if used with LUKS2 format
 that supports per-keyslot parameters. For LUKS1, PBKDF type and hash
diff --git a/man/cryptsetup-luksDump.8.adoc b/man/cryptsetup-luksDump.8.adoc
index f9f3910..b1b3907 100644
--- a/man/cryptsetup-luksDump.8.adoc
+++ b/man/cryptsetup-luksDump.8.adoc
@@ -40,7 +40,7 @@ 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].
+--volume-key-file, --type, --unbound, --key-slot, --timeout, --external-tokens-path].
 
 *WARNING:* If --dump-volume-key is used with --key-file and the argument
 to --key-file is '-', no validation question will be asked and no
diff --git a/man/cryptsetup-luksFormat.8.adoc b/man/cryptsetup-luksFormat.8.adoc
index be241f8..c9c3565 100644
--- a/man/cryptsetup-luksFormat.8.adoc
+++ b/man/cryptsetup-luksFormat.8.adoc
@@ -29,6 +29,8 @@ in use, e.g., mounted filesystem, used in LVM, active RAID member, etc. The
 device or filesystem has to be un-mounted in order to call luksFormat.
 
 To use specific version of LUKS format, use _--type luks1_ or _type luks2_.
+To use OPAL hardware encryption on a self-encrypting drive, use
+_--hw-opal_ or _--hw-opal-only_.
 
 *<options>* can be [--hash, --cipher, --verify-passphrase, --key-size,
 --key-slot, --key-file (takes precedence over optional second argument),
@@ -41,7 +43,7 @@ For LUKS2, additional *<options>* can be [--integrity,
 --integrity-no-wipe, --sector-size, --label, --subsystem, --pbkdf,
 --pbkdf-memory, --pbkdf-parallel, --disable-locks, --disable-keyring,
 --luks2-metadata-size, --luks2-keyslots-size, --keyslot-cipher,
---keyslot-key-size, --integrity-legacy-padding].
+--keyslot-key-size, --integrity-legacy-padding, --hw-opal, --hw-opal-only].
 
 *WARNING:* Doing a luksFormat on an existing LUKS container will make
 all data in the old container permanently irretrievable unless you have a
diff --git a/man/cryptsetup-luksResume.8.adoc b/man/cryptsetup-luksResume.8.adoc
index 9d81cbc..ba9f690 100644
--- a/man/cryptsetup-luksResume.8.adoc
+++ b/man/cryptsetup-luksResume.8.adoc
@@ -23,7 +23,8 @@ interactively for a passphrase if no token is usable (LUKS2 only) or
 *<options>* can be [--key-file, --keyfile-size, --keyfile-offset,
 --key-slot, --header, --disable-keyring, --disable-locks, --token-id,
 --token-only, --token-type, --disable-external-tokens, --type, --tries,
---timeout, --verify-passphrase].
+--timeout, --verify-passphrase, --volume-key-keyring, --link-vk-to-keyring,
+--external-tokens-path].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]
diff --git a/man/cryptsetup-luksSuspend.8.adoc b/man/cryptsetup-luksSuspend.8.adoc
index ed20681..c5f90ce 100644
--- a/man/cryptsetup-luksSuspend.8.adoc
+++ b/man/cryptsetup-luksSuspend.8.adoc
@@ -20,6 +20,10 @@ Suspends an active device (all IO operations will block and accesses to
 the device will wait indefinitely) and wipes the encryption key from
 kernel memory. Needs kernel 2.6.19 or later.
 
+While the _luksSuspend_ operation wipes encryption keys from memory,
+it does not remove possible plaintext data in various caches or in-kernel
+metadata for mounted filesystems.
+
 After this operation, you have to use _luksResume_ to reinstate the
 encryption key and unblock the device or _close_ to remove the mapped
 device.
diff --git a/man/cryptsetup-open.8.adoc b/man/cryptsetup-open.8.adoc
index 5e8e7a6..73a5dc5 100644
--- a/man/cryptsetup-open.8.adoc
+++ b/man/cryptsetup-open.8.adoc
@@ -35,18 +35,22 @@ is inverted for historical reasons, all other aliases use the standard
 *<device> <name>* order.
 
 === PLAIN
-*open --type plain <device> <name>* +
+*open --type plain <device> <name>* --cipher <spec> --key-size <bits> --hash <alg> +
 plainOpen <device> <name> (*old syntax*) +
 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 is used) then also *--hash* to avoid incompatibility as
+default values can be different in older cryptsetup versions. +
+
 *<options>* can be [--hash, --cipher, --verify-passphrase, --sector-size,
 --key-file, --keyfile-size, --keyfile-offset, --key-size, --offset,
 --skip, --device-size, --size, --readonly, --shared, --allow-discards,
 --refresh, --timeout, --verify-passphrase, --iv-large-sectors].
 
-Example: 'cryptsetup open --type plain /dev/sda10 e1' maps the raw
+Example: 'cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --hash sha256 /dev/sda10 e1' maps the raw
 encrypted device /dev/sda10 to the mapped (decrypted) device
 /dev/mapper/e1, which can then be mounted, fsck-ed or have a filesystem
 created on it.
@@ -74,7 +78,8 @@ matching PIN protected token.
 --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].
+--verify-passphrase, --persistent, --volume-key-keyring, --link-vk-to-keyring,
+--external-tokens-path].
 
 === loopAES
 *open --type loopaes <device> <name> --key-file <keyfile>* +
@@ -150,6 +155,11 @@ Opens the BITLK (a BitLocker compatible) <device> and sets up a mapping
 --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.
+
 === FileVault2
 *open --type fvault2 <device> <name>* +
 fvault2Open <device> <name> (*old syntax*)
diff --git a/man/cryptsetup-reencrypt.8.adoc b/man/cryptsetup-reencrypt.8.adoc
index 154a469..387b0a9 100644
--- a/man/cryptsetup-reencrypt.8.adoc
+++ b/man/cryptsetup-reencrypt.8.adoc
@@ -31,7 +31,7 @@ which otherwise require full on-disk data change (re-encryption). The
 _reencrypt_ action reencrypts data on LUKS device in-place.
 
 You can regenerate *volume key* (the real key used in on-disk encryption
-unclocked by passphrase), *cipher*, *cipher mode* or *encryption sector size*
+unlocked by passphrase), *cipher*, *cipher mode* or *encryption sector size*
 (LUKS2 only).
 
 Reencryption process may be safely interrupted by a user via SIGINT
@@ -43,7 +43,7 @@ options available for _luksFormat_ action for respective LUKS version (see
 cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8).
 
 *NOTE* that for encrypt and decrypt mode, the whole device must be
-treated as unencrypted -- there are no quarantees of confidentiality as
+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.*
diff --git a/man/cryptsetup-resize.8.adoc b/man/cryptsetup-resize.8.adoc
index 4cff482..b9a5502 100644
--- a/man/cryptsetup-resize.8.adoc
+++ b/man/cryptsetup-resize.8.adoc
@@ -36,7 +36,7 @@ keyring is used by default for LUKS2 devices.
 *<options>* can be [--size, --device-size, --token-id, --token-only,
 --token-type, --key-slot, --key-file, --keyfile-size, --keyfile-offset,
 --timeout, --disable-external-tokens, --disable-locks, --disable-keyring,
---verify-passphrase, --timeout].
+--verify-passphrase, --timeout, --external-tokens-path].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]
diff --git a/man/cryptsetup-token.8.adoc b/man/cryptsetup-token.8.adoc
index 7a3a069..5fa6af8 100644
--- a/man/cryptsetup-token.8.adoc
+++ b/man/cryptsetup-token.8.adoc
@@ -49,7 +49,7 @@ 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].
+--json-file, --token-replace, --unbound, --external-tokens-path].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]
diff --git a/man/cryptsetup.8.adoc b/man/cryptsetup.8.adoc
index ddd3a12..442012d 100644
--- a/man/cryptsetup.8.adoc
+++ b/man/cryptsetup.8.adoc
@@ -21,7 +21,8 @@ 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.
+volumes, TrueCrypt, VeraCrypt, BitLocker and FileVault2 compatible volumes,
+and for hardware-based encryption on OPAL capable drives.
 
 For more information about specific cryptsetup action see
 *cryptsetup-<action>*(8), where *<action>* is the name of the
@@ -423,15 +424,44 @@ Opens the FVAULT2 (a FileVault2-compatible) <device> (usually the second
 partition on the device) and sets up a mapping <name>. +
 See *cryptsetup-open*(8).
 
-=== DUMP
-*fvault2Dump <device>*
+== 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).
+
+*WARNING:* this support is new and experimental, and requires at least kernel
+v6.4. Resizing devices is not supported.
+
+*--hw-opal* can be specified for OPAL + dm-crypt, and
+*--hw-opal-only* can be specified to use OPAL only, without a dm-crypt layer.
+
+Opening, closing and enrolling tokens work in the same way as with LUKS2 and
+dm-crypt. The new parameters are only necessary when formatting, the LUKS2
+metadata will ensure the right setup is performed when opening or closing. If
+no *subsystem* is specified, it will be automatically set to *HW-OPAL* so that
+it is immediately apparent when a device uses OPAL.
 
-Dump the header information of an FVAULT2 device. +
-See *cryptsetup-fvault2Dump*(8).
+=== 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.
+
+=== ERASE
+*erase <device>*
 
-Note that cryptsetup does not use any macOS code or proprietary
-specifications. Please report all problems related to this compatibility
-extension to the cryptsetup project.
+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.
+*WARNING*: a factory reset will cause ALL data on the device to be lost,
+regardless of the partition it is ran on, if any, and regardless of any LUKS2
+header backup.
 
 == MISCELLANEOUS ACTIONS
 
@@ -671,11 +701,13 @@ 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.
+integrity protection, use *--integrity* option (see *cryptsetup-luksFormat(8)*).
 
-Since dm-integrity doesn't support discards (TRIM), dm-crypt device on
-top of it inherits this, so integrity protection mode doesn't support
-discards either.
+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-luksFormat(8)*).
 
 Some integrity modes requires two independent keys (key for encryption
 and for authentication). Both these keys are stored in one LUKS keyslot.
diff --git a/man/integritysetup.8.adoc b/man/integritysetup.8.adoc
index 2aec1a6..e89b0f7 100644
--- a/man/integritysetup.8.adoc
+++ b/man/integritysetup.8.adoc
@@ -44,6 +44,10 @@ create <name> <device> (*OBSOLETE syntax*)
 
 Open a mapping with <name> backed by device <device>.
 
+If the integrity algorithm of the device is non-default,
+then the algorithm should be specified with the *--integrity* option.
+This will not be detected from the device.
+
 *<options>* can be [--data-device, --batch-mode, --journal-watermark,
 --journal-commit-time, --buffer-sectors, --integrity,
 --integrity-key-size, --integrity-key-file, --integrity-no-journal,
diff --git a/man/meson.build b/man/meson.build
new file mode 100644
index 0000000..5013093
--- /dev/null
+++ b/man/meson.build
@@ -0,0 +1,256 @@
+fs = import('fs')
+
+adocfiles_common = [
+    'common_options.adoc',
+    'common_footer.adoc',
+]
+
+manpage_tuples_to_build = []
+manpage_tuples_all = []
+
+# tuple with adoc file and generated aliases
+cryptsetup_manpages = [
+    [
+        'cryptsetup.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-open.8.adoc',
+        [
+            'cryptsetup-create.8',
+            'cryptsetup-plainOpen.8',
+            'cryptsetup-luksOpen.8',
+            'cryptsetup-loopaesOpen.8',
+            'cryptsetup-tcryptOpen.8',
+            'cryptsetup-bitlkOpen.8',
+        ],
+    ],
+    [
+        'cryptsetup-close.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-reencrypt.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-status.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-resize.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-refresh.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksFormat.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksSuspend.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksResume.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksAddKey.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksRemoveKey.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksConvertKey.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksKillSlot.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksChangeKey.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-erase.8.adoc',
+        [
+            'cryptsetup-luksErase.8',
+        ],
+    ],
+    [
+        'cryptsetup-luksUUID.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-isLuks.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksDump.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksHeaderBackup.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-luksHeaderRestore.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-token.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-convert.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-config.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-tcryptDump.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-bitlkDump.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-fvault2Dump.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-repair.8.adoc',
+        [],
+    ],
+    [
+        'cryptsetup-benchmark.8.adoc',
+        [],
+    ],
+]
+
+veritysetup_manpages = [
+    [
+        'veritysetup.8.adoc',
+        [],
+    ],
+]
+integritysetup_manpages = [
+    [
+        'integritysetup.8.adoc',
+        [],
+    ],
+]
+sshplugin_manpages = [
+    [
+        'cryptsetup-ssh.8.adoc',
+        [],
+    ],
+]
+
+if get_option('cryptsetup')
+    manpage_tuples_to_build += cryptsetup_manpages
+endif
+manpage_tuples_all += cryptsetup_manpages
+if get_option('veritysetup')
+    manpage_tuples_to_build += veritysetup_manpages
+endif
+manpage_tuples_all += veritysetup_manpages
+if get_option('integritysetup')
+    manpage_tuples_to_build += integritysetup_manpages
+endif
+manpage_tuples_all += integritysetup_manpages
+if get_option('ssh-token')
+    manpage_tuples_to_build += sshplugin_manpages
+endif
+manpage_tuples_all += sshplugin_manpages
+
+adocfiles_all = []
+foreach tuple : manpage_tuples_all
+    adocfiles_all += tuple[0]
+endforeach
+
+prebuilt_manpages_exist = true
+foreach manpage_tuple : manpage_tuples_to_build
+    adocfile = manpage_tuple[0]
+    aliases = manpage_tuple[1]
+    manfile = fs.replace_suffix(adocfile, '')
+
+    prebuilt_manpages_exist = prebuilt_manpages_exist and fs.exists(manfile)
+
+    foreach alias : aliases
+        prebuilt_manpages_exist = prebuilt_manpages_exist and fs.exists(alias)
+    endforeach
+endforeach
+
+built_manpages = []
+
+if use_asciidoc
+    meson.add_dist_script(find_program('meson_dist_convert.sh'),
+        asciidoc, meson.project_version(), adocfiles_all)
+
+    foreach manpage_tuple : manpage_tuples_to_build
+        adocfile = manpage_tuple[0]
+        aliases = manpage_tuple[1]
+
+        mandir = join_paths(get_option('prefix'), get_option('mandir'), 'man8')
+        manfile = fs.replace_suffix(adocfile, '')
+
+        built_manpages += custom_target(manfile,
+            command: [
+                asciidoc,
+                '-b', 'manpage',
+                '--failure-level', 'ERROR',
+                '-a', 'release-version=@0@'.format(
+                    meson.project_version(),
+                ),
+                '-o', '@BASENAME@',
+                '@INPUT@',
+                '--destination-dir=@0@'.format(
+                    meson.current_build_dir(),
+                ),
+                '--base-dir=@SOURCE_ROOT@',
+            ],
+            input: adocfile,
+            depend_files: adocfiles_common,
+            install: true,
+            install_dir: mandir,
+            output: [
+                manfile,
+            ] + aliases,
+        )
+    endforeach
+else
+    # use_asciidoc == false
+    if prebuilt_manpages_exist
+        message('Using prebuilt manpages.')
+        foreach manpage_tuple : manpage_tuples_to_build
+            adocfile = manpage_tuple[0]
+            aliases = manpage_tuple[1]
+            manfile = fs.replace_suffix(adocfile, '')
+
+            install_man(manfile)
+            foreach alias : aliases
+                install_man(alias)
+            endforeach
+        endforeach
+    else
+        warning('Neither asciidoctor nor prebuilt manual pages found. Skipping manpage installation')
+    endif
+endif
+
+man = custom_target(
+    'man',
+    output: 'man',
+    depends: built_manpages,
+    command: [
+        nop_command,
+    ])
diff --git a/man/meson_dist_convert.sh b/man/meson_dist_convert.sh
new file mode 100755
index 0000000..3b55d05
--- /dev/null
+++ b/man/meson_dist_convert.sh
@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# generates manpages from AsciiDoc files when building dist tarball
+# run asciidoctor in parallel on `nproc` cores
+
+set -e
+
+[ -z "$MESON_DIST_ROOT" ] && echo "This script is meant to be run only from meson while generating dist tarball." && exit 1
+
+if [ $# -lt 3 ]; then
+        echo "Usage: $0 <asciidoctor path> <release version> <adocfiles>"
+        exit 1
+fi
+
+ASCIIDOCTOR="$1"
+RELEASE_VERSION="$2"
+shift 2
+
+cd $MESON_DIST_ROOT/man
+i=1
+N=$(nproc)
+for adocfile in "$@"
+do
+    $ASCIIDOCTOR -b manpage --failure-level ERROR -a release-version=$RELEASE_VERSION --base-dir=$MESON_DIST_ROOT $adocfile &
+    if [ $(( $i % $N )) -eq 0 ]; then wait; fi
+    i=$((i+1))
+done