man: document OPAL support

Signed-off-by: Luca Boccassi <bluca@debian.org>

3 files changed, 46 insertions, 10 deletions

diff --git a/man/cryptsetup-erase.8.adoc b/man/cryptsetup-erase.8.adoc
index 97a13aac..a8bbc586 100644
--- a/man/cryptsetup-erase.8.adoc
+++ b/man/cryptsetup-erase.8.adoc
@@ -21,8 +21,12 @@ Erase all keyslots and make the LUKS container permanently inaccessible.
 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.
 
-*<options>* can be [--header, --disable-locks].
+*<options>* can be [--header, --disable-locks, --hw-opal-factory-reset].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]
diff --git a/man/cryptsetup-luksFormat.8.adoc b/man/cryptsetup-luksFormat.8.adoc
index be241f8e..c9c3565a 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.8.adoc b/man/cryptsetup.8.adoc
index ddd3a127..ded1c483 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.
 
-Dump the header information of an FVAULT2 device. +
-See *cryptsetup-fvault2Dump*(8).
+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.
 
-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.
+=== 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>*
+
+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