ci: Add debian unstable (sid)

crypt_activate_by_keyslot_context never respected pbkdf serialation
flag (CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF).

In fact it worked only when device was activated via passphrase or via
passphrase file. It was never respected when device was activated
by a token for example.

When the internal code was fully switched to activation via keyslot
context the legacy code for passphrase based activation was dropped
and we lost track of serialization flag completely.

This fixes all of the issues so now the serialization flag will be
respected also with tokens (and all other activation methods unlocking
LUKS2 keyslot with memory hard pbkdf).

Fixes: 58385d68d8 (Allow activation via keyslot context)
Fixes: #968.

.gitlab-ci.yml

@@ -10,7 +10,6 @@ include:
   - local: .gitlab/ci/debian.yml
   - local: .gitlab/ci/fedora.yml
   - local: .gitlab/ci/fedora-opal.yml
-  - local: .gitlab/ci/rhel.yml
   - local: .gitlab/ci/centos.yml
 #  - local: .gitlab/ci/annocheck.yml
   - local: .gitlab/ci/csmock.yml
@@ -22,4 +21,3 @@ include:
   - local: .gitlab/ci/alpinelinux.yml
   - local: .gitlab/ci/debian-i686.yml
   - local: .gitlab/ci/cifuzz.yml
-  - local: .gitlab/ci/ubuntu.yml

.gitlab/ci/alpinelinux.yml

@@ -7,8 +7,10 @@
     - >
       sudo apk add
       lvm2-dev openssl-dev popt-dev util-linux-dev json-c-dev
-      argon2-dev device-mapper which sharutils gettext gettext-dev automake
+      argon2-dev device-mapper which sharutils gettext-dev argp-standalone automake
       autoconf libtool build-base keyutils tar jq expect git asciidoctor
+    # Be sure we have updated basic tools and system
+    - sudo apk upgrade gcc binutils build-base musl
     - ./autogen.sh
     - ./configure --prefix=/usr --libdir=/lib --sbindir=/sbin --disable-static --enable-libargon2 --with-crypto_backend=openssl --disable-external-tokens --disable-ssh-token --enable-asciidoc
 

.gitlab/ci/centos.yml

@@ -1,6 +1,4 @@
 .centos-openssl-backend:
-  variables:
-    DISTRO: cryptsetup-centos-stream-9
   extends:
     - .fail_if_coredump_generated
   before_script:
@@ -29,6 +27,7 @@ test-main-commit-centos-stream9:
   stage: test
   interruptible: true
   variables:
+    DISTRO: cryptsetup-centos-stream-9
     RUN_SSH_PLUGIN_TEST: "1"
     RUN_KEYRING_TRUSTED_TEST: "1"
   rules:
@@ -51,6 +50,53 @@ test-mergerq-centos-stream9:
   stage: test
   interruptible: true
   variables:
+    DISTRO: cryptsetup-centos-stream-9
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
+      when: never
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - make -j
+    - make -j -C tests check-programs
+    - sudo -E make check
+
+test-main-commit-centos-stream10:
+  extends:
+    - .centos-openssl-backend
+  tags:
+    - libvirt
+    - cryptsetup-centos-stream-10
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-centos-stream-10
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
+      when: never
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
+  script:
+    - make -j
+    - make -j -C tests check-programs
+    - sudo -E make check
+
+test-mergerq-centos-stream10:
+  extends:
+    - .centos-openssl-backend
+  tags:
+    - libvirt
+    - cryptsetup-centos-stream-10
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-centos-stream-10
     RUN_SSH_PLUGIN_TEST: "1"
     RUN_KEYRING_TRUSTED_TEST: "1"
   rules:

.gitlab/ci/cibuild-setup-ubuntu.sh

@@ -45,11 +45,3 @@ fi
 
 DEBIAN_FRONTEND=noninteractive apt-get -yq install "${PACKAGES[@]}"
 apt-get -y build-dep cryptsetup
-
-echo "====================== VERSIONS ==================="
-if [[ $COMPILER == "clang" ]]; then
-	echo "Using scan-build${COMPILER_VERSION:+-$COMPILER_VERSION}"
-fi
-
-${COMPILER}-$COMPILER_VERSION -v
-echo "====================== END VERSIONS ==================="

.gitlab/ci/compilation-clang.gitlab-ci.yml

@@ -4,26 +4,54 @@ test-clang-compilation:
   script:
     - export CFLAGS="-Wall -Werror"
     - ./autogen.sh
+    - $CC --version
     - ./configure
     - make -j
     - make -j check-programs
 
-test-clang-Wall-script:
+test-clang-Wall-script-ubuntu:
   extends:
     - .gitlab-shared-clang
   script:
     - export CFLAGS="-g -O0"
     - export CC="$CI_PROJECT_DIR/.gitlab/ci/clang-Wall"
     - ./autogen.sh
+    - $CC --version
     - ./configure
     - make -j CFLAGS="-g -O0 -Werror"
     - make -j CFLAGS="-g -O0 -Werror" check-programs
 
-test-scan-build:
+test-clang-Wall-script-alpine:
+  extends:
+    - .gitlab-shared-clang-alpine
+  allow_failure: true
+  script:
+    - export CFLAGS="-g -O0"
+    - export CC="$CI_PROJECT_DIR/.gitlab/ci/clang-Wall"
+    - ./autogen.sh
+    - $CC --version
+    - ./configure
+    - make -j CFLAGS="-g -O0 -Werror"
+    - make -j CFLAGS="-g -O0 -Werror" check-programs
+
+test-scan-build-ubuntu:
   extends:
     - .gitlab-shared-clang
   script:
     - ./autogen.sh
+    - echo "scan-build${COMPILER_VERSION:+-$COMPILER_VERSION}"
+    - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} -V ./configure CFLAGS="-g -O0"
+    - make clean
+    - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} --status-bugs -maxloop 10 make -j
+    - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} --status-bugs -maxloop 10 make -j check-programs
+
+test-scan-build-alpine:
+  extends:
+    - .gitlab-shared-clang-alpine
+  allow_failure: true
+  script:
+    - ./autogen.sh
+    - echo "scan-build${COMPILER_VERSION:+-$COMPILER_VERSION}"
     - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} -V ./configure CFLAGS="-g -O0"
     - make clean
     - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} --status-bugs -maxloop 10 make -j
@@ -52,6 +80,7 @@ test-scan-build-backends:
     - DEBIAN_FRONTEND=noninteractive apt-get -yq install libgcrypt20-dev libnss3-dev nettle-dev libmbedtls-dev
     - ./autogen.sh
     - echo "Configuring with crypto backend $BACKENDS"
+    - echo "scan-build${COMPILER_VERSION:+-$COMPILER_VERSION}"
     - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} -V ./configure CFLAGS="-g -O0" --with-crypto_backend=$BACKENDS
     - make clean
     - scan-build${COMPILER_VERSION:+-$COMPILER_VERSION} --status-bugs -maxloop 10 make -j

.gitlab/ci/compilation-gcc.gitlab-ci.yml

@@ -4,30 +4,57 @@ test-gcc-compilation:
   script:
     - export CFLAGS="-Wall -Werror"
     - ./autogen.sh
+    - $CC --version
     - ./configure
     - make -j
     - make -j check-programs
 
-test-gcc-Wall-script:
+test-gcc-Wall-script-ubuntu:
   extends:
     - .gitlab-shared-gcc
   script:
     - export CFLAGS="-g -O0"
     - export CC="$CI_PROJECT_DIR/.gitlab/ci/gcc-Wall"
     - ./autogen.sh
+    - $CC --version
     - ./configure
     - make -j CFLAGS="-g -O0 -Werror"
     - make -j CFLAGS="-g -O0 -Werror" check-programs
 
-test-gcc-fanalyzer:
+test-gcc-Wall-script-alpine:
+  extends:
+    - .gitlab-shared-gcc-alpine
+  allow_failure: true
+  script:
+    - export CFLAGS="-g -O0"
+    - export CC="$CI_PROJECT_DIR/.gitlab/ci/gcc-Wall"
+    - ./autogen.sh
+    - $CC --version
+    - ./configure
+    - make -j CFLAGS="-g -O0 -Werror"
+    - make -j CFLAGS="-g -O0 -Werror" check-programs
+
+test-gcc-fanalyzer-ubuntu:
   extends:
     - .gitlab-shared-gcc
   script:
     - ./autogen.sh
+    - $CC --version
     - ./configure CFLAGS="-Wall -Werror -g -O0 -fanalyzer -fdiagnostics-path-format=separate-events" --host=x86_64
     - make -j
     - make -j check-programs
 
+test-gcc-fanalyzer-alpine:
+  extends:
+    - .gitlab-shared-gcc-alpine
+  allow_failure: true
+  script:
+    - ./autogen.sh
+    - $CC --version
+    - ./configure CFLAGS="-Wall -Werror -g -O0 -fanalyzer -fdiagnostics-path-format=separate-events -Wno-analyzer-fd-leak" --host=x86_64
+    - make -j
+    - make -j check-programs
+
 test-gcc-fanalyzer-backends:
   extends:
     - .gitlab-shared-gcc
@@ -50,6 +77,7 @@ test-gcc-fanalyzer-backends:
   script:
     - DEBIAN_FRONTEND=noninteractive apt-get -yq install libgcrypt20-dev libnss3-dev nettle-dev libmbedtls-dev
     - ./autogen.sh
+    - $CC --version
     - echo "Configuring with crypto backend $BACKENDS"
     - ./configure CFLAGS="-Wall -Werror -g -O0 -fanalyzer -fdiagnostics-path-format=separate-events" --host=x86_64 --with-crypto_backend=$BACKENDS
     - make -j

.gitlab/ci/debian.yml

@@ -17,6 +17,48 @@
     - ./configure --enable-libargon2 --enable-asciidoc
 
 test-mergerq-job-debian:
+  extends:
+    - .debian-prep
+  tags:
+    - libvirt
+    - cryptsetup-debian-unstable
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-debian-unstable
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - make -j
+    - make -j -C tests check-programs
+    - sudo -E make check
+
+test-main-commit-job-debian:
+  extends:
+    - .debian-prep
+  tags:
+    - libvirt
+    - cryptsetup-debian-unstable
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-debian-unstable
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
+  script:
+    - make -j
+    - make -j -C tests check-programs
+    - sudo -E make check
+
+test-mergerq-job-debian12:
   extends:
     - .debian-prep
   tags:
@@ -37,7 +79,7 @@ test-mergerq-job-debian:
     - make -j -C tests check-programs
     - sudo -E make check
 
-test-main-commit-job-debian:
+test-main-commit-job-debian12:
   extends:
     - .debian-prep
   tags:
@@ -60,6 +102,50 @@ test-main-commit-job-debian:
 
 # meson tests
 test-mergerq-job-debian-meson:
+  extends:
+    - .debian-prep
+  tags:
+    - libvirt
+    - cryptsetup-debian-unstable
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-debian-unstable
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - sudo apt-get -y install -y -qq meson ninja-build
+    - meson setup build
+    - ninja -C build
+    - cd build && sudo -E meson test --verbose --print-errorlogs
+
+test-main-commit-job-debian-meson:
+  extends:
+    - .debian-prep
+  tags:
+    - libvirt
+    - cryptsetup-debian-unstable
+  stage: test
+  interruptible: true
+  variables:
+    DISTRO: cryptsetup-debian-unstable
+    RUN_SSH_PLUGIN_TEST: "1"
+    RUN_KEYRING_TRUSTED_TEST: "1"
+  rules:
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
+  script:
+    - sudo apt-get -y install -y -qq meson ninja-build
+    - meson setup build
+    - ninja -C build
+    - cd build && sudo -E meson test --verbose --print-errorlogs
+
+test-mergerq-job-debian12-meson:
   extends:
     - .debian-prep
   tags:
@@ -81,7 +167,7 @@ test-mergerq-job-debian-meson:
     - ninja -C build
     - cd build && sudo -E meson test --verbose --print-errorlogs
 
-test-main-commit-job-debian-meson:
+test-main-commit-job-debian12-meson:
   extends:
     - .debian-prep
   tags:

.gitlab/ci/fedora.yml

@@ -30,6 +30,7 @@ test-main-commit-job-rawhide:
   variables:
     RUN_SSH_PLUGIN_TEST: "1"
     RUN_KEYRING_TRUSTED_TEST: "1"
+    RUN_SYSTEMD_PLUGIN_TEST: "1"
   rules:
     - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
       when: never
@@ -51,6 +52,7 @@ test-mergerq-job-rawhide:
   variables:
     RUN_SSH_PLUGIN_TEST: "1"
     RUN_KEYRING_TRUSTED_TEST: "1"
+    RUN_SYSTEMD_PLUGIN_TEST: "1"
   rules:
     - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
       when: never

.gitlab/ci/gcc-Wall

@@ -36,7 +36,8 @@ EXTRA="-Wextra \
  -Wmaybe-uninitialized \
  -Wvla \
  -Wformat-overflow \
- -Wformat-truncation"
+ -Wformat-truncation \
+ -Wstringop-overread"
 
 exec $GCC $PEDANTIC $CONVERSION \
 	-Wall $Wuninitialized \

.gitlab/ci/gitlab-shared-docker.yml

@@ -1,4 +1,5 @@
-.gitlab-shared-docker:
+# Ubuntu
+.gitlab-shared-docker-ubuntu:
   image: ubuntu:noble
   tags:
     - gitlab-org-docker
@@ -13,20 +14,48 @@
     - export CC="${COMPILER}${COMPILER_VERSION:+-$COMPILER_VERSION}"
     - export CXX="${COMPILER}++${COMPILER_VERSION:+-$COMPILER_VERSION}"
 
+# Alpine
+.gitlab-shared-docker-alpine:
+  image: alpine:latest
+  tags:
+    - gitlab-org-docker
+  stage: test
+  interruptible: true
+  rules:
+    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
+  before_script:
+    - apk add bash build-base clang clang-analyzer argp-standalone lvm2-dev openssl-dev popt-dev util-linux-dev json-c-dev device-mapper gettext-dev libssh-dev automake autoconf libtool tar asciidoctor
+    - export CC="${COMPILER}${COMPILER_VERSION:+-$COMPILER_VERSION}"
+    - export CXX="${COMPILER}++${COMPILER_VERSION:+-$COMPILER_VERSION}"
+
 .gitlab-shared-gcc:
   extends:
-    - .gitlab-shared-docker
+    - .gitlab-shared-docker-ubuntu
   variables:
     COMPILER: "gcc"
     COMPILER_VERSION: "14"
     CC: "gcc-14"
-    RUN_SSH_PLUGIN_TEST: "1"
 
 .gitlab-shared-clang:
   extends:
-    - .gitlab-shared-docker
+    - .gitlab-shared-docker-ubuntu
   variables:
     COMPILER: "clang"
-    COMPILER_VERSION: "19"
+    COMPILER_VERSION: "20"
-    CC: "clang-19"
+    CC: "clang-20"
-    RUN_SSH_PLUGIN_TEST: "1"
+
+.gitlab-shared-gcc-alpine:
+  extends:
+    - .gitlab-shared-docker-alpine
+  variables:
+    COMPILER: "gcc"
+    CC: "gcc"
+
+.gitlab-shared-clang-alpine:
+  extends:
+    - .gitlab-shared-docker-alpine
+  variables:
+    COMPILER: "clang"
+    CC: "clang"

.gitlab/ci/rhel.yml

@@ -1,157 +0,0 @@
-.rhel-openssl-backend:
-  extends:
-    - .fail_if_coredump_generated
-  before_script:
-    - >
-      sudo yum -y -q  install
-      autoconf automake device-mapper-devel gcc gettext-devel json-c-devel
-      libblkid-devel libpwquality-devel libselinux-devel libssh-devel libtool
-      libuuid-devel make popt-devel libsepol-devel nc openssh-clients passwd
-      pkgconfig sharutils sshpass tar uuid-devel vim-common device-mapper
-      expect gettext git jq keyutils openssl-devel openssl gem
-    - sudo gem install asciidoctor
-    - sudo -E git clean -xdf
-    - ./autogen.sh
-    - ./configure --enable-fips --enable-pwquality --with-crypto_backend=openssl --enable-asciidoc
-
-# non-FIPS jobs
-
-test-main-commit-rhel8:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-8
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-rhel-8
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-test-main-commit-rhel9:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-9
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-rhel-9
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-test-main-commit-rhel10:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-10
-  stage: test
-  interruptible: true
-  allow_failure: true
-  variables:
-    DISTRO: cryptsetup-rhel-10
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-# FIPS jobs
-
-test-main-commit-rhel8-fips:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-8-fips
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-rhel-8-fips
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - grep -q fips=1 /proc/cmdline || exit 1
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-test-main-commit-rhel9-fips:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-9-fips
-  stage: test
-  interruptible: true
-  allow_failure: true
-  variables:
-    DISTRO: cryptsetup-rhel-9-fips
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - grep -q fips=1 /proc/cmdline || exit 1
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-test-main-commit-rhel10-fips:
-  extends:
-    - .rhel-openssl-backend
-  tags:
-    - libvirt
-    - cryptsetup-rhel-10-fips
-  stage: test
-  interruptible: true
-  allow_failure: true
-  variables:
-    DISTRO: cryptsetup-rhel-10-fips
-    RUN_SSH_PLUGIN_TEST: "1"
-  rules:
-    - if: $RUN_SYSTEMD_PLUGIN_TEST != null
-      when: never
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - grep -q fips=1 /proc/cmdline || exit 1
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check

.gitlab/ci/ubuntu.yml

@@ -1,106 +0,0 @@
-.ubuntu-prep:
-  extends:
-    - .fail_if_coredump_generated
-  before_script:
-    - sudo apt-get -y update
-    - >
-      sudo apt-get -y install -y -qq git gcc make autoconf automake autopoint
-      pkgconf libtool libtool-bin gettext libssl-dev libdevmapper-dev
-      libpopt-dev uuid-dev libsepol-dev libjson-c-dev libssh-dev libblkid-dev
-      tar libargon2-dev libpwquality-dev sharutils dmsetup jq xxd expect
-      keyutils netcat-openbsd passwd openssh-client sshpass asciidoctor
-      swtpm meson ninja-build python3-jinja2 gperf libcap-dev libtss2-dev
-      libmount-dev swtpm-tools tpm2-tools
-    # scsi_debug, gost crypto
-    - sudo apt-get -y install dkms linux-headers-$(uname -r) linux-modules-extra-$(uname -r) gost-crypto-dkms
-    - sudo apt-get -y build-dep cryptsetup
-    - sudo -E git clean -xdf
-    - ./autogen.sh
-    - ./configure --enable-libargon2 --enable-asciidoc
-
-test-mergerq-job-ubuntu:
-  extends:
-    - .ubuntu-prep
-  tags:
-    - libvirt
-    - cryptsetup-ubuntu-2404
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-ubuntu-2404
-    RUN_SSH_PLUGIN_TEST: "1"
-    RUN_KEYRING_TRUSTED_TEST: "1"
-  rules:
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-  script:
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-test-main-commit-job-ubuntu:
-  extends:
-    - .ubuntu-prep
-  tags:
-    - libvirt
-    - cryptsetup-ubuntu-2404
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-ubuntu-2404
-    RUN_SSH_PLUGIN_TEST: "1"
-    RUN_KEYRING_TRUSTED_TEST: "1"
-  rules:
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - make -j
-    - make -j -C tests check-programs
-    - sudo -E make check
-
-# meson tests
-test-mergerq-job-ubuntu-meson:
-  extends:
-    - .ubuntu-prep
-  tags:
-    - libvirt
-    - cryptsetup-ubuntu-2404
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-ubuntu-2404
-    RUN_SSH_PLUGIN_TEST: "1"
-    RUN_KEYRING_TRUSTED_TEST: "1"
-  rules:
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-  script:
-    - sudo apt-get -y install -y -qq meson ninja-build
-    - meson setup build
-    - ninja -C build
-    - cd build && sudo -E meson test --verbose --print-errorlogs
-
-test-main-commit-job-ubuntu-meson:
-  extends:
-    - .ubuntu-prep
-  tags:
-    - libvirt
-    - cryptsetup-ubuntu-2404
-  stage: test
-  interruptible: true
-  variables:
-    DISTRO: cryptsetup-ubuntu-2404
-    RUN_SSH_PLUGIN_TEST: "1"
-    RUN_KEYRING_TRUSTED_TEST: "1"
-  rules:
-    - if: $CI_PROJECT_PATH != "cryptsetup/cryptsetup"
-      when: never
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH =~ /v2\..\.x$/
-  script:
-    - sudo apt-get -y install -y -qq meson ninja-build
-    - meson setup build
-    - ninja -C build
-    - cd build && sudo -E meson test --verbose --print-errorlogs

CONTRIBUTING.md

@@ -119,7 +119,7 @@ libtool --mode=execute gdb --args ./cryptsetup --debug $@
 This will ensure that a properly compiled libcryptsetup file is used.
 
 ### Coding style
-Cryptsetup uses [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html) for libcryptsetup and tools (where applicable) with some additional notes:
+Cryptsetup uses [Linux kernel coding style](https://cdn.kernel.org/doc/html/latest/process/coding-style.html) for libcryptsetup and tools (where applicable) with some additional notes:
 - Use tabulators for indentation; the line should not exceed 100 characters with an 8-character tabulator. Otherwise, use a tab of any length. :-).
 - The minimal C standard required is C99.
 - The ``goto`` use is allowed only for error path (``goto out`` for common code path, ``goto err`` for specific error code path).

FAQ.md

@@ -38,7 +38,7 @@
   LUKS1 and LUKS2.
  
   The LUKS1 on-disk format specification is at  
-  https://www.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf  
+  https://cdn.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf  
   The LUKS2 on-disk format specification is at  
   https://gitlab.com/cryptsetup/LUKS2-docs
 

Makefile.am

@@ -9,6 +9,7 @@ EXTRA_DIST += meson_options.txt \
 	scripts/meson.build \
 	src/meson.build \
 	tests/meson.build \
+	tests/fuzz/meson.build \
 	tokens/meson.build \
 	tokens/ssh/meson.build
 
@@ -24,8 +25,7 @@ AM_CPPFLAGS = \
         -DLIBDIR=\""$(libdir)"\"                \
         -DPREFIX=\""$(prefix)"\"                \
         -DSYSCONFDIR=\""$(sysconfdir)"\"        \
-        -DVERSION=\""$(VERSION)"\"              \
+        -DVERSION=\""$(VERSION)"\"
-        -DEXTERNAL_LUKS2_TOKENS_PATH=\"${EXTERNAL_LUKS2_TOKENS_PATH}\"
 AM_CFLAGS = -Wall
 AM_CXXFLAGS = -Wall
 AM_LDFLAGS =

README.md

@@ -30,28 +30,22 @@ which enables users to transport or migrate data seamlessly.
   * The latest version of the
   [LUKS2 format specification](https://gitlab.com/cryptsetup/LUKS2-docs).
   * The latest version of the
-  [LUKS1 format specification](https://www.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf).
+  [LUKS1 format specification](https://cdn.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf).
   * [Project home page](https://gitlab.com/cryptsetup/cryptsetup/).
   * [Frequently asked questions (FAQ)](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions)
 
 Download
 --------
 Release notes and tarballs are available at
-[kernel.org](https://www.kernel.org/pub/linux/utils/cryptsetup/).
+[kernel.org](https://cdn.kernel.org/pub/linux/utils/cryptsetup/).
 
-**The latest stable cryptsetup release version is 2.7.5**
+**The latest stable cryptsetup release version is 2.8.1**
-  * [cryptsetup-2.7.5.tar.xz](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.7/cryptsetup-2.7.5.tar.xz)
+  * [cryptsetup-2.8.1.tar.xz](https://cdn.kernel.org/pub/linux/utils/cryptsetup/v2.8/cryptsetup-2.8.1.tar.xz)
-  * Signature [cryptsetup-2.7.5.tar.sign](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.7/cryptsetup-2.7.5.tar.sign)
+  * Signature [cryptsetup-2.8.1.tar.sign](https://cdn.kernel.org/pub/linux/utils/cryptsetup/v2.8/cryptsetup-2.8.1.tar.sign)
     _(You need to decompress file first to check signature.)_
-  * [Cryptsetup 2.7.5 Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.7/v2.7.5-ReleaseNotes).
+  * [Cryptsetup 2.8.1 Release Notes](https://cdn.kernel.org/pub/linux/utils/cryptsetup/v2.8/v2.8.1-ReleaseNotes).
 
-Previous versions
+[Previous versions](https://cdn.kernel.org/pub/linux/utils/cryptsetup)
- * [Version 2.6.1](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.6/cryptsetup-2.6.1.tar.xz) -
-   [Signature](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.6/cryptsetup-2.6.1.tar.sign) -
-   [Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes).
- * [Version 1.7.5](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/cryptsetup-1.7.5.tar.xz) -
-   [Signature](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/cryptsetup-1.7.5.tar.sign) -
-   [Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.5-ReleaseNotes).
 
 Source and API documentation
 ----------------------------
@@ -76,7 +70,7 @@ Below are the packages needed to build for certain Linux distributions:
 
 **For Fedora**:
 ```
-git gcc make autoconf automake gettext-devel pkgconfig openssl-devel popt-devel device-mapper-devel libuuid-devel json-c-devel libblkid-devel findutils libtool libssh-devel tar
+git gcc make autoconf automake gettext-devel pkgconfig openssl-devel popt-devel device-mapper-devel libuuid-devel json-c-devel libblkid-devel findutils libtool libssh-devel tar rubygem-asciidoctor
 
 Optionally: libargon2-devel libpwquality-devel
 ```
@@ -87,7 +81,7 @@ sharutils device-mapper jq vim-common expect keyutils netcat shadow-utils openss
 
 **For Debian and Ubuntu**:
 ```
-git gcc make autoconf automake autopoint pkg-config libtool gettext libssl-dev libdevmapper-dev libpopt-dev uuid-dev libsepol-dev libjson-c-dev libssh-dev libblkid-dev tar
+git gcc make autoconf automake autopoint pkg-config libtool gettext libssl-dev libdevmapper-dev libpopt-dev uuid-dev libsepol-dev libjson-c-dev libssh-dev libblkid-dev tar asciidoctor
 
 Optionally: libargon2-0-dev libpwquality-dev
 ```

configure.ac

@@ -1,9 +1,9 @@
 AC_PREREQ([2.67])
-AC_INIT([cryptsetup],[2.8.0-rc0])
+AC_INIT([cryptsetup],[2.9.0-git])
 
 dnl library version from <major>.<minor>.<release>[-<suffix>]
 LIBCRYPTSETUP_VERSION=$(echo $PACKAGE_VERSION | cut -f1 -d-)
-LIBCRYPTSETUP_VERSION_INFO=25:0:11
+LIBCRYPTSETUP_VERSION_INFO=23:0:11
 
 AM_SILENT_RULES([yes])
 AC_CONFIG_SRCDIR(src/cryptsetup.c)
@@ -680,8 +680,36 @@ AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[
 ])
 CFLAGS=$saved_CFLAGS
 
+dnl Force compiler to use zero_call_used_regs("used") to check for the function attribute support.
+dnl Otherwise the compiler may falsely advertise it with __has_attribute operator, even though
+dnl it does not implement it on some archs.
+AC_MSG_CHECKING([for zero_call_used_regs(user)])
+saved_CFLAGS=$CFLAGS
+CFLAGS="-O0 -Werror"
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[
+	void _test_function(void);
+	__attribute__((zero_call_used_regs("used"))) void _test_function(void) {
+		volatile int *i; volatile int j = 0; if (j) *i = 0;
+	}
+]],
+[[ _test_function() ]]
+)],[
+	AC_DEFINE([HAVE_ATTRIBUTE_ZEROCALLUSEDREGS], 1, [Define to 1 to use __attribute__((zero_call_used_regs("used")))])
+	AC_MSG_RESULT([yes])
+], [
+	AC_MSG_RESULT([no])
+])
+CFLAGS=$saved_CFLAGS
+
 AC_MSG_CHECKING([for systemd tmpfiles config directory])
-PKG_CHECK_VAR([systemd_tmpfilesdir], [systemd], [tmpfilesdir], [], [systemd_tmpfilesdir=no])
+if test "x$prefix" != "xNONE"; then
+	saved_PKG_CONFIG=$PKG_CONFIG
+	PKG_CONFIG="$PKG_CONFIG --define-variable=prefix='${prefix}'"
+	PKG_CHECK_VAR([systemd_tmpfilesdir], [systemd], [tmpfilesdir], [], [systemd_tmpfilesdir=no])
+	PKG_CONFIG=$saved_PKG_CONFIG
+else
+	PKG_CHECK_VAR([systemd_tmpfilesdir], [systemd], [tmpfilesdir], [], [systemd_tmpfilesdir=no])
+fi
 AC_MSG_RESULT([$systemd_tmpfilesdir])
 
 AC_SUBST([DEVMAPPER_LIBS])
@@ -795,8 +823,9 @@ CS_NUM_WITH([verity-hash-block], [hash block size for verity mode], [4096])
 CS_NUM_WITH([verity-salt-size],  [salt size for verity mode], [32])
 CS_NUM_WITH([verity-fec-roots],  [parity bytes for verity FEC], [2])
 
-CS_STR_WITH([tmpfilesdir], [override default path to directory with systemd temporary files], [])
+AC_ARG_WITH([tmpfilesdir],
-test -z "$with_tmpfilesdir" && with_tmpfilesdir=$systemd_tmpfilesdir
+	AS_HELP_STRING([--with-tmpfilesdir=DIR], [override default path to directory with systemd temporary files]),
+	[], [with_tmpfilesdir=$systemd_tmpfilesdir])
 test "x$with_tmpfilesdir" = "xno" || {
 	CS_ABSPATH([${with_tmpfilesdir}],[with-tmpfilesdir])
 	DEFAULT_TMPFILESDIR=$with_tmpfilesdir
@@ -815,7 +844,9 @@ test -z "$with_luks2_lock_dir_perms" && with_luks2_lock_dir_perms=0700
 DEFAULT_LUKS2_LOCK_DIR_PERMS=$with_luks2_lock_dir_perms
 AC_SUBST(DEFAULT_LUKS2_LOCK_DIR_PERMS)
 
-CS_STR_WITH([luks2-external-tokens-path], [path to directory with LUKSv2 external token handlers (plugins)], [LIBDIR/cryptsetup])
+AC_ARG_WITH([luks2-external-tokens-path],
+	AS_HELP_STRING([--with-luks2-external-tokens-path=DIR], [path to directory with LUKSv2 external token handlers (plugins)]),
+	[], [with_luks2_external_tokens_path=""])
 if test -n "$with_luks2_external_tokens_path"; then
 	CS_ABSPATH([${with_luks2_external_tokens_path}],[with-luks2-external-tokens-path])
 	EXTERNAL_LUKS2_TOKENS_PATH=$with_luks2_external_tokens_path
@@ -823,6 +854,17 @@ else
 	EXTERNAL_LUKS2_TOKENS_PATH="\${libdir}/cryptsetup"
 fi
 AC_SUBST(EXTERNAL_LUKS2_TOKENS_PATH)
+dnl We need to define expanded EXTERNAL_LUKS2_TOKENS_PATH, but some other code can depend on prefix=NONE.
+dnl Pretend you do not see this hack :-)
+saved_prefix=$prefix
+saved_exec_prefix=$exec_prefix
+test "x$prefix" = "xNONE" && prefix="$ac_default_prefix"
+test "x$exec_prefix" = "xNONE" && exec_prefix="$prefix"
+expanded_EXTERNAL_LUKS2_TOKENS_PATH=$(eval echo "$EXTERNAL_LUKS2_TOKENS_PATH")
+expanded_EXTERNAL_LUKS2_TOKENS_PATH=$(eval echo "$expanded_EXTERNAL_LUKS2_TOKENS_PATH")
+AC_DEFINE_UNQUOTED([EXTERNAL_LUKS2_TOKENS_PATH], ["$expanded_EXTERNAL_LUKS2_TOKENS_PATH"], [path to directory with LUKSv2 external token handlers (plugins)])
+prefix=$saved_prefix
+exec_prefix=$saved_exec_prefix
 
 dnl Override default LUKS format version (for cryptsetup or cryptsetup-reencrypt format actions only).
 AC_ARG_WITH([default_luks_format],

docs/v2.8.0-ReleaseNotes

@@ -0,0 +1,328 @@
+Cryptsetup 2.8.0 Release Notes
+==============================
+Stable release with new features and bug fixes
+
+All users of cryptsetup 2.7 must upgrade to this version.
+
+Changes since version 2.7.5
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Introduce support for inline mode (use HW sectors with additional hardware metadata space).
+
+  Some enterprise NVMe drives allow formatting sector size with additional metadata space,
+  for example, sector size 4096 bytes + 64 bytes for metadata.
+  We hope common firmware will soon support such features in more recent models.
+
+  If this metadata space is available (not internally used by a data integrity profile),
+  it removes the need to use the dm-integrity layer for sector metadata allocation.
+  This means that the performance bottleneck caused by the dm-integrity journal is eliminated.
+
+  Note: such drive must be reformatted with an external nvme tool.
+  You can check for support (reported as LBA format) by running the command
+    "nvme id-ns -H <nvme device>" and then you can reformat to the selected profile
+  (with complete data loss) with "nvme format -l <lbaf>.
+  This way, you can also reformat NVMe drive to 4096-byte sectors,which is strongly recommended
+  for encryption performance.
+
+  The required device mapper for inline mode was introduced in Linux kernel version 6.11.
+
+  The inline mode can be used with the new --integrity-inline option.
+
+  For integritysetup, the kernel dm-integrity layer is still used, but it directly maps metadata
+  to the hardware (eliminating the journal).
+  For cryptsetup, the dm-integrity layer is eliminated, and only the dm-crypt kernel driver is used.
+  The libcryptsetup exports a new crypt_format_inline API call.
+
+  Examples (underlying device must provide inline HW metadata space):
+
+  Use integritysetup format with inline mode with default CRC32 checksums:
+
+   # integritysetup format --sector-size 4096 --integrity-inline <device> [--no-wipe]
+   # integritysetup open <device> test
+   # integritysetup status test
+     /dev/mapper/test is active.
+       type:    INTEGRITY
+       tag size: 4 [bytes]
+       integrity: crc32c
+       device: <device>
+       sector size:  4096 [bytes]
+       ...
+       inline mode
+       journal: not active
+
+  Use LUKS2 with authenticated encryption (here with AEGIS AEAD cipher):
+
+   # cryptsetup luksFormat --integrity-inline --integrity aead --sector-size 4096 \
+                -c aegis128-random --key-size 128 <device> [--integrity-no-wipe]
+   # cryptsetup open <device> test
+   # cryptsetup luksDump <device>
+     ...
+     Requirements:   inline-hw-tags
+
+  After format, the inline mode is used automatically, and no special options are needed.
+  Please check the manual pages for more details about used options.
+
+  Note that the LUKS2 authenticated encryption is still an experimental feature.
+  The inline mode only improves performance by removing the dm-integrity layer.
+
+* Finalize use of keyslot context API.
+
+  Keyslot context is a generic abstraction over keyslot manipulation.
+  It extends many exiting commands by additional functions like tokens in activation, resume,
+  reencryption and similar commands without introducing new specific API functions.
+
+* Make all keyslot context types fully self-contained.
+
+  In the previous version, the caller is responsible for releasing of some allocated memory.
+  In this version, all memory is allocated internally. The existing keyslot context API function
+  provides backward compatibility through versioned symbols.
+
+* Add --key-description and --new-key-description cryptsetup options.
+
+  These can be used for the specification of the keyring with passphrase retrieval in the open,
+  resize, luksResume, luksFormat, luksAddKey and luksDump.
+
+* Support more precise keyslot selection in reencryption initialization.
+
+  Reencryption must update stored keys in keyslots, so it needs to unlock all keyslots first.
+
+  When no specific keyslot is selected by the --key-slot option, all active keyslots are updated.
+
+  Users may narrow down the selection of keyslots by specifying either --token-id, --token-type
+  or --token-only option. Only keyslots associated with the specific token (--token-id) or
+  a specific type (--token-type) or any token (--token-only) will be updated.
+  All other keyslots will be erased after reencryption is finished.
+
+  During reencryption, there are two volume keys (old and new).
+  For very specific use cases, reencryption can also be initialized by providing
+  volume keys directly by --volume-key-file, --new-volume-key-file, --volume-key-keyring
+  or --new-volume-key-keyring options. These options allow reencryption of the device with
+  no active keyslots (these can be added later).
+  If the --force-no-keyslots option is specified, all active keyslots will be erased after
+  the reencryption operation is finished.
+
+* Allow reencryption to resume using token and volume keys.
+
+  The reencryption can be resumed using tokens (similar to initialization described above).
+  For very specific use cases, reencryption can be resumed by providing volume keys.
+
+* Cryptsetup repair command now tries to check LUKS keyslot areas for corruption.
+
+  A keyslot binary area contains an encrypted volume key diffused to a larger area by
+  the anti-forensic splitter. If this area is corrupted, the keyslot can no longer be unlocked,
+  even with the correct password.
+
+  Active keyslot area should look like random data, so some specific corruption can be detected
+  by randomness analysis.
+
+  Cryptsetup repair command now tries to analyze the area expecting a uniform distribution
+  of bytes in 4096-byte blocks. If a problem is detected, it tries to localize corruption
+  in a smaller block (using the expected bit count).
+  Both tests are based on the Chi-squared statistical test.
+
+  This analysis can replace the external keyslot check program and usually is more sensitive.
+  However, it cannot detect all corruptions and can produce false positives.
+
+  Please use it as a hint when your password is no longer accepted, and you suspect
+  header corruption. This is the example output of the analysis:
+
+  # cryptsetup repair <device>
+    Keyslot 2 binary data could be corrupted.
+      Suspected offset: 0x88000
+    You can use hexdump -v -C -n 128 -s <offset_0xXXXX> <device> to inspect the data.
+
+  The test does not modify the header. A keyslot corruption cannot be repaired.
+  You have to use a backup header.
+
+* Opal2 SED: PSID keyfile is now expected to be 32 alphanumeric characters.
+
+  If the keyfile size is not explicitly set, it uses only first 32 bytes.
+  All Opal2 manufacturers seem to use PSID of this length.
+
+* Opal2: Avoid the Erase method and use Secure Erase for locking range.
+
+  The Erase method is defined for Single-user mode (SUM) and works on SUM-enabled locking ranges.
+  As we do not use SUM yet, this always fails and falls back to Secure erase anyway.
+
+* Opal2: Fix some error description (in debug only).
+
+  Some Opal error messages were incorrect.
+  Cryptsetup now use all codes according to TCG specifications.
+
+* Opal2: Do not allow deferred deactivation.
+
+  The self-encrypting drive must be locked immediately; deferred deactivation is not supported.
+
+* Allow --reduce-device-size and --device-size combination for reencryption (encrypt) action.
+
+  For some very specific cases, this can be used to encrypt only part of the device together
+  with allocation a new space for the LUKS header.
+
+* Fix the userspace storage backend to support kernel "capi:" cipher specification format.
+
+  This avoids unnecessary fallback to the device-mapper instead of the userspace crypto library
+  in luksFormat. The "capi:" is Linux kernel cryptographic format.
+  For example, capi:xts(aes)-plain64 is equivalent of aes-xts-plain64.
+
+* Disallow conversion from LUKS2 to LUKS1 if kernel "capi:" cipher specification is used.
+
+  LUKS1 never officially supported this cipher specification format.
+  Such devices cannot be converted to LUKS1 (while existing devices can still be activated).
+
+* Explicitly disallow kernel "capi:" cipher specification format for LUKS2 keyslot encryption.
+
+  This specification is intended to be used for data encryption, not for keyslots.
+
+* Do not allow conversion of LUKS2 to LUKS1 if an unbound keyslot is present.
+
+  LUKS1 does not support unbound keyslots. Such devices cannot be converted.
+
+* cryptsetup: Adjust the XTS key size for kernel "capi:" cipher specification.
+
+  Double key size as there are two keys the same way as for dm-crypt format.
+
+* Remove keyslot warning about possible failure due to low memory.
+
+  This check was intended to warn users about possible out-of-memory situations
+  but produced many false positives.
+
+* Do not limit Argon2 KDF memory cost on systems with more than 4GB of available memory.
+
+  The memory cost is intended to be limited only in low-memory situations (like virtual machines
+  without swap), not on systems with plenty of RAM.
+
+* Properly report out of memory error for cryptographic backends implementing Argon2.
+
+* Avoid KDF2 memory cost overflow on 32-bit platforms.
+
+* Do not use page size as a fallback for device block size.
+
+  This check produced wrong values if used on platforms with larger page sizes (64kB)
+  and specific underlying storage (like ZFS).
+
+* veritysetup: Check hash device size in advance.
+
+  If hashes are stored in a file image, allocate the size in advance.
+  For a block device, check if hashes (Merkle tree) fits the device.
+
+* Print a better error message for unsupported LUKS2 AEAD device resize.
+
+* Optimize LUKS2 metadata writes.
+
+  LUKS2 supports several JSON area length configurations. Do not write full metadata
+  (including padding), as it may generate noticeable overhead with LUKS2.
+
+* veritysetup: support --error-as-corruption option.
+
+  The panic/restart_on_error options were introduced in Linux kernel 6.12 and process errors
+  (like media read error) the same way as data corruption.
+  Use this flag in combination with --panic-on-corruption or --restart-on-corruption.
+
+* Report all sizes in status and dump command output in the correct units.
+
+  Since the support of --sector-size option, the meaning of "sectors" became ambiguous as it
+  usually means 512-byte sectors (device-mapper unit). Confusion occurs when the sector size
+  is 4096 bytes while units used for display are 512-byte sectors.
+
+  All status commands in tools now display units explicitly to avoid confusion.
+
+  For example:
+  # cryptsetup status test
+    ...
+    sector size:  4096 [bytes]
+    offset:  32768 [512-byte units] (134217728 [bytes])
+    size:    7501443760 [512-byte units] (30725913640960 [bytes])
+
+  If you parse the output of status commands, please check your scripts to ensure they work
+  with the new output properly.
+
+* Add --integrity-key-size option to cryptsetup.
+
+  This option can be used to set up non-standard integrity key size (e.g. for HMAC).
+  It adds a new (optional) JSON "key_size" attribute in the segment.integrity JSON object
+  (see updated LUKS2 specification). If not set, the code uses selected hash length size.
+
+* Support trusted & encrypted keyrings for plain devices.
+
+* Support plain format resize with a keyring key.
+
+  If a plain dm-crypt device references the keyring, cryptsetup now allows resizing.
+  The user must ensure that the key in the keyring is unchanged since activation.
+  Otherwise, reloading the key can cause data corruption after an unexpected key change.
+
+* TCRYPT: Clear mapping of system-encrypted partitions.
+
+  TrueCrypt/VeraCrypt supports full system encryption (only a partition table is not encrypted)
+  or system partition encryption (only a system partition is encrypted).
+  The metadata header then contains the offset and size of the encrypted area.
+  Cryptsetup needs to know the specific partition offset to calculate encryption parameters.
+
+  To properly map a partition, the user must specify a real partition device so cryptsetup
+  can calculate this offset. As the partition can be an image in a file, cryptsetup now tries
+  to determine proper parameters and use device size stored in VeraCrypt metadata.
+
+  Please see the manual page description (TCRYPT section) for a detailed description.
+
+* TCRYPT: Print all information from the decrypted metadata header in the tcryptDump command.
+
+  Print also volume sizes (if present) and flags.
+
+* Always lock the volume key structure in memory.
+
+  Some memory for safe allocation was not allocated from locked (unswappable) memory.
+  Older cryptsetup locked all memory. Selective locking was introduced in version 2.6.0.
+
+* Do not run direct-io read check on block devices.
+
+  Block devices always support direct-io.
+  This check produced unnecessary error with locked Opal2 devices.
+
+* Fix a possible segfault in deferred deactivation.
+
+  Thanks Clément Guérin for the report.
+
+* Exclude cipher allocation time from the cryptsetup benchmark.
+
+* Add Mbed-TLS optional crypto backend.
+
+  Mbed-TLS is a tiny TLS implementation designed for embedded environments.
+  The backend can be enabled with the --with-crypto_backend=mbedtls configure option.
+
+* Fix the wrong preprocessor use of #ifdef for config.h processed by Meson.
+
+  Cryptsetup supports Autoconf and, optionally, Meson configuration.
+  Part of the code wrongly used #ifdef instead of #if conditional sections.
+  This caused problems with Meson-generated config.h.
+
+* Reorganize license files.
+
+  The license text files are now in docs/licenses.
+  The COPYING file in the root directory is the default license.
+
+Libcryptsetup API extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The libcryptsetup API is backward compatible with all existing symbols.
+
+Due to the self-contained memory allocation, these symbols have the new version
+ crypt_keyslot_context_init_by_passphrase;
+ crypt_keyslot_context_init_by_keyfile;
+ crypt_keyslot_context_init_by_token;
+ crypt_keyslot_context_init_by_volume_key;
+ crypt_keyslot_context_init_by_signed_key;
+ crypt_keyslot_context_init_by_keyring;
+ crypt_keyslot_context_init_by_vk_in_keyring;
+
+New symbols:
+ crypt_format_inline
+ crypt_get_old_volume_key_size
+ crypt_reencrypt_init_by_keyslot_context
+ crypt_safe_memcpy
+
+New defines:
+ CRYPT_ACTIVATE_HIGH_PRIORITY
+ CRYPT_ACTIVATE_ERROR_AS_CORRUPTION
+ CRYPT_ACTIVATE_INLINE_MODE
+ CRYPT_REENCRYPT_CREATE_NEW_DIGEST
+
+New requirement flag:
+ CRYPT_REQUIREMENT_INLINE_HW_TAGS

docs/v2.8.1-ReleaseNotes

@@ -0,0 +1,40 @@
+Cryptsetup 2.8.1 Release Notes
+==============================
+Stable bug-fix release with minor extensions.
+
+All users of cryptsetup 2.8.0 must upgrade to this version.
+
+Changes since version 2.8.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Fix status and deactivation of TCRYPT (VeraCrypt compatible) devices that use chained ciphers.
+
+* Fix unlocking BITLK (BitLocker compatible) devices with multibyte UTF8 characters in the passphrase.
+
+* Do not allow activation of the LUKS2 device if the used keyslot is not encrypted (it uses a null cipher).
+
+  Such a configuration cannot be created by cryptsetup, but can be crafted outside of it.
+  Null cipher is sometimes used to create an empty container for later reencryption.
+  Only an empty passphrase can activate such a container (the same as in LUKS1).
+
+* Do not silently decrease PBKDF parallel cost (threads) if set by an option.
+  The maximum parallel cost is limited to 4 threads.
+
+* Fixes to configuration and installation scripts.
+
+  Meson and autoconf tools now properly support --prefix option for temporary directory installation.
+  Multiple fixes and cleanups to config.h for compatibility between Meson and autoconf.
+  Fix the luks2-external-tokens-path Meson option to work the same as in autoconf.
+  Fix Meson install for tool binaries, install fvault2Open man page and include test/fuzz/meson.build in release.
+
+* Major update to manual pages.
+
+  Try to explain the PBKDF hardcoded limits.
+  Add a better explanation for automatic integrity tag recalculation.
+  Mention crypt/verity/integritytab.
+  Remove or reformulate some misleading warnings present only with old and no longer supported kernels.
+  Clarify that some commands do not wipe data and unify OPAL reset wording.
+  Clarify the --label option.
+  There are also many other grammar and stylistic fixes to unify the man-page style.
+
+* Fixes for false-positive and annoying (optional) warnings added in recent compilers.

lib/bitlk/bitlk.c

@@ -111,6 +111,7 @@ struct bitlk_superblock {
 struct bitlk_fve_metadata {
 	/* FVE metadata block header */
 	uint8_t signature[8];
+	/* size of this block (in 16-byte units) */
 	uint16_t fve_size;
 	uint16_t fve_version;
 	uint16_t curr_state;
@@ -132,6 +133,32 @@ struct bitlk_fve_metadata {
 	uint64_t creation_time;
 } __attribute__ ((packed));
 
+struct bitlk_validation_hash {
+	uint16_t size;
+	uint16_t role;
+	uint16_t type;
+	uint16_t flags;
+	/* likely a hash type code, anything other than 0x2005 isn't supported */
+	uint16_t hash_type;
+	uint16_t unknown1;
+	/* SHA-256 */
+	uint8_t hash[32];
+} __attribute__ ((packed));
+
+struct bitlk_fve_metadata_validation {
+	/* FVE metadata validation block header */
+	uint16_t validation_size;
+	uint16_t validation_version;
+	uint32_t fve_crc32;
+	/* this is a single nested structure's header defined here for simplicity */
+	uint16_t nested_struct_size;
+	uint16_t nested_struct_role;
+	uint16_t nested_struct_type;
+	uint16_t nested_struct_flags;
+	/* datum containing a similar nested structure (encrypted using VMK) with hash (SHA256) */
+	uint8_t nested_struct_data[BITLK_VALIDATION_VMK_DATA_SIZE];
+} __attribute__ ((packed));
+
 struct bitlk_entry_header_block {
 	uint64_t offset;
 	uint64_t size;
@@ -237,10 +264,11 @@ static int parse_vmk_entry(struct crypt_device *cd, uint8_t *data, int start, in
 	bool supported = false;
 	int r = 0;
 
-	/* only passphrase or recovery passphrase vmks are supported (can be used to activate) */
+	/* only passphrase, recovery passphrase, startup key and clearkey vmks are supported (can be used to activate) */
 	supported = (*vmk)->protection == BITLK_PROTECTION_PASSPHRASE ||
 		    (*vmk)->protection == BITLK_PROTECTION_RECOVERY_PASSPHRASE ||
-		    (*vmk)->protection == BITLK_PROTECTION_STARTUP_KEY;
+		    (*vmk)->protection == BITLK_PROTECTION_STARTUP_KEY ||
+		    (*vmk)->protection == BITLK_PROTECTION_CLEAR_KEY;
 
 	while ((end - start) >= (ssize_t)(sizeof(key_entry_size) + sizeof(key_entry_type) + sizeof(key_entry_value))) {
 		/* size of this entry */
@@ -297,17 +325,13 @@ static int parse_vmk_entry(struct crypt_device *cd, uint8_t *data, int start, in
 			crypt_volume_key_add_next(&((*vmk)->vk), vk);
 		/* clear key for a partially decrypted volume */
 		} else if (key_entry_value == BITLK_ENTRY_VALUE_KEY) {
-			/* We currently don't want to support opening a partially decrypted
+			/* For clearkey protection, we need to store this key */
-			 * device so we don't need to store this key.
+			key_size = key_entry_size - (BITLK_ENTRY_HEADER_LEN + 4);
-			 *
+			key = (const char *) data + start + BITLK_ENTRY_HEADER_LEN + 4;
-			 * key_size = key_entry_size - (BITLK_ENTRY_HEADER_LEN + 4);
+			vk = crypt_alloc_volume_key(key_size, key);
-			 * key = (const char *) data + start + BITLK_ENTRY_HEADER_LEN + 4;
+			if (vk == NULL)
-			 * vk = crypt_alloc_volume_key(key_size, key);
+				return -ENOMEM;
-			 * if (vk == NULL)
+			crypt_volume_key_add_next(&((*vmk)->vk), vk);
-			 * 	return -ENOMEM;
-			 * crypt_volume_key_add_next(&((*vmk)->vk), vk);
-			 */
-			log_dbg(cd, "Skipping clear key metadata entry.");
 		/* unknown timestamps in recovery protected VMK */
 		} else if (key_entry_value == BITLK_ENTRY_VALUE_RECOVERY_TIME) {
 			;
@@ -361,6 +385,54 @@ static int parse_vmk_entry(struct crypt_device *cd, uint8_t *data, int start, in
 	return 0;
 }
 
+static bool check_fve_metadata(struct bitlk_fve_metadata *fve)
+{
+	if (memcmp(fve->signature, BITLK_SIGNATURE, sizeof(fve->signature)) || le16_to_cpu(fve->fve_version) != 2 ||
+		(fve->fve_size << 4) > BITLK_FVE_METADATA_SIZE)
+		return false;
+
+	return true;
+}
+
+static bool check_fve_metadata_validation(struct bitlk_fve_metadata_validation *validation)
+{
+	/* only check if there is room for CRC-32, the actual size must be larger */
+	if (le16_to_cpu(validation->validation_size) < 8 || le16_to_cpu(validation->validation_version > 2))
+		return false;
+
+	return true;
+}
+
+static bool parse_fve_metadata_validation(struct bitlk_metadata *params, struct bitlk_fve_metadata_validation *validation)
+{
+	/* extra checks for a nested structure (MAC) and BITLK FVE metadata */
+
+	if (le16_to_cpu(validation->validation_size) < sizeof(struct bitlk_fve_metadata_validation))
+		return false;
+
+	if (le16_to_cpu(validation->nested_struct_size != BITLK_VALIDATION_VMK_HEADER_SIZE + BITLK_VALIDATION_VMK_DATA_SIZE) ||
+		le16_to_cpu(validation->nested_struct_role) != 0 ||
+		le16_to_cpu(validation->nested_struct_type) != 5)
+		return false;
+
+	/* nonce */
+	memcpy(params->validation->nonce,
+		validation->nested_struct_data,
+		BITLK_NONCE_SIZE);
+
+	/* MAC tag */
+	memcpy(params->validation->mac_tag,
+		validation->nested_struct_data + BITLK_NONCE_SIZE,
+		BITLK_VMK_MAC_TAG_SIZE);
+
+	/* AES-CCM encrypted datum with SHA256 hash */
+	memcpy(params->validation->enc_datum,
+		validation->nested_struct_data + BITLK_NONCE_SIZE + BITLK_VMK_MAC_TAG_SIZE,
+		BITLK_VALIDATION_VMK_DATA_SIZE - BITLK_NONCE_SIZE - BITLK_VMK_MAC_TAG_SIZE);
+
+	return true;
+}
+
 void BITLK_bitlk_fvek_free(struct bitlk_fvek *fvek)
 {
 	if (!fvek)
@@ -391,6 +463,7 @@ void BITLK_bitlk_metadata_free(struct bitlk_metadata *metadata)
 
 	free(metadata->guid);
 	free(metadata->description);
+	free(metadata->validation);
 	BITLK_bitlk_vmk_free(metadata->vmks);
 	BITLK_bitlk_fvek_free(metadata->fvek);
 }
@@ -402,20 +475,25 @@ int BITLK_read_sb(struct crypt_device *cd, struct bitlk_metadata *params)
 	struct bitlk_signature sig = {};
 	struct bitlk_superblock sb = {};
 	struct bitlk_fve_metadata fve = {};
+	struct bitlk_fve_metadata_validation validation = {};
 	struct bitlk_entry_vmk entry_vmk = {};
 	uint8_t *fve_entries = NULL;
+	uint8_t *fve_validated_block = NULL;
 	size_t fve_entries_size = 0;
 	uint32_t fve_metadata_size = 0;
+	uint32_t fve_size_real = 0;
 	int fve_offset = 0;
 	char guid_buf[UUID_STR_LEN] = {0};
 	uint16_t entry_size = 0;
 	uint16_t entry_type = 0;
 	int i = 0;
 	int r = 0;
+	int valid_fve_metadata_idx = -1;
 	int start = 0;
 	size_t key_size = 0;
 	const char *key = NULL;
 	char *description = NULL;
+	struct crypt_hash *hash;
 
 	struct bitlk_vmk *vmk = NULL;
 	struct bitlk_vmk *vmk_p = params->vmks;
@@ -490,15 +568,80 @@ int BITLK_read_sb(struct crypt_device *cd, struct bitlk_metadata *params)
 	for (i = 0; i < 3; i++)
 		params->metadata_offset[i] = le64_to_cpu(sb.fve_offset[i]);
 
-	log_dbg(cd, "Reading BITLK FVE metadata of size %zu on device %s, offset %" PRIu64 ".",
+	fve_validated_block = malloc(BITLK_FVE_METADATA_SIZE);
-		sizeof(fve), device_path(device), params->metadata_offset[0]);
+	if (fve_validated_block == NULL) {
+		r = -ENOMEM;
+		goto out;
+	}
 
-	/* read FVE metadata from the first metadata area */
+	for (i = 0; i < 3; i++) {
-	if (read_lseek_blockwise(devfd, device_block_size(cd, device),
+		/* iterate over FVE metadata copies and pick the valid one */
-		device_alignment(device), &fve, sizeof(fve), params->metadata_offset[0]) != sizeof(fve) ||
+		log_dbg(cd, "Reading BITLK FVE metadata copy #%d of size %zu on device %s, offset %" PRIu64 ".",
-		memcmp(fve.signature, BITLK_SIGNATURE, sizeof(fve.signature)) ||
+			i, sizeof(fve), device_path(device), params->metadata_offset[i]);
-		le16_to_cpu(fve.fve_version) != 2) {
+
-		log_err(cd, _("Failed to read BITLK FVE metadata from %s."), device_path(device));
+		if (read_lseek_blockwise(devfd, device_block_size(cd, device),
+			device_alignment(device), &fve, sizeof(fve), params->metadata_offset[i]) != sizeof(fve) ||
+			!check_fve_metadata(&fve) ||
+			(fve_size_real = le16_to_cpu(fve.fve_size) << 4, read_lseek_blockwise(devfd, device_block_size(cd, device),
+			device_alignment(device), &validation, sizeof(validation), params->metadata_offset[i] + fve_size_real) != sizeof(validation)) ||
+			!check_fve_metadata_validation(&validation) ||
+			/* double-fetch is here, but we aren't validating MAC */
+			read_lseek_blockwise(devfd, device_block_size(cd, device), device_alignment(device), fve_validated_block, fve_size_real,
+			params->metadata_offset[i]) != fve_size_real ||
+			(crypt_crc32(~0, fve_validated_block, fve_size_real) ^ ~0) != le32_to_cpu(validation.fve_crc32)) {
+			/* found an invalid FVE metadata copy, log and skip */
+			log_dbg(cd, _("Failed to read or validate BITLK FVE metadata copy #%d from %s."), i, device_path(device));
+		} else {
+			/* found a valid FVE metadata copy, use it */
+			valid_fve_metadata_idx = i;
+			break;
+		}
+	}
+
+	if (valid_fve_metadata_idx < 0) {
+		/* all FVE metadata copies are invalid, fail */
+		log_err(cd, _("Failed to read and validate BITLK FVE metadata from %s."), device_path(device));
+		r = -EINVAL;
+		goto out;
+	}
+
+	/* check that a valid FVE metadata block is in its expected location */
+	if (params->metadata_offset[valid_fve_metadata_idx] != le64_to_cpu(fve.fve_offset[valid_fve_metadata_idx])) {
+		log_err(cd, _("Failed to validate the location of BITLK FVE metadata from %s."), device_path(device));
+		r = -EINVAL;
+		goto out;
+	}
+
+	/* update offsets from a valid FVE metadata copy */
+	for (i = 0; i < 3; i++)
+		params->metadata_offset[i] = le64_to_cpu(fve.fve_offset[i]);
+
+	/* check that the FVE metadata hasn't changed between reads, because we are preparing for the MAC check */
+	if (memcmp(&fve, fve_validated_block, sizeof(fve)) != 0) {
+		log_err(cd, _("BITLK FVE metadata changed between reads from %s."), device_path(device));
+		r = -EINVAL;
+		goto out;
+	}
+
+	crypt_backend_memzero(&params->sha256_fve, 32);
+	if (crypt_hash_init(&hash, "sha256")) {
+		log_err(cd, _("Failed to hash BITLK FVE metadata read from %s."), device_path(device));
+		r = -EINVAL;
+		goto out;
+	}
+	crypt_hash_write(hash, (const char *)fve_validated_block, fve_size_real);
+	crypt_hash_final(hash, (char *)&params->sha256_fve, 32);
+	crypt_hash_destroy(hash);
+
+	/* do some extended checks against FVE metadata, but not including MAC verification */
+	params->validation = malloc(sizeof(struct bitlk_validation));
+	if (!params->validation) {
+		r = -ENOMEM;
+		goto out;
+	}
+
+	if (!parse_fve_metadata_validation(params, &validation)) {
+		log_err(cd, _("Failed to parse BITLK FVE validation metadata from %s."), device_path(device));
 		r = -EINVAL;
 		goto out;
 	}
@@ -583,17 +726,18 @@ int BITLK_read_sb(struct crypt_device *cd, struct bitlk_metadata *params)
 	}
 	memset(fve_entries, 0, fve_entries_size);
 
-	log_dbg(cd, "Reading BITLK FVE metadata entries of size %zu on device %s, offset %" PRIu64 ".",
+	log_dbg(cd, "Getting BITLK FVE metadata entries of size %zu on device %s, offset %" PRIu64 ".",
-		fve_entries_size, device_path(device), params->metadata_offset[0] + BITLK_FVE_METADATA_HEADERS_LEN);
+		fve_entries_size, device_path(device), params->metadata_offset[valid_fve_metadata_idx] + BITLK_FVE_METADATA_HEADERS_LEN);
 
-	if (read_lseek_blockwise(devfd, device_block_size(cd, device),
+	if (BITLK_FVE_METADATA_HEADERS_LEN + fve_entries_size > fve_size_real) {
-		device_alignment(device), fve_entries, fve_entries_size,
+		log_err(cd, _("Failed to check BITLK metadata entries previously read from %s."), device_path(device));
-		params->metadata_offset[0] + BITLK_FVE_METADATA_HEADERS_LEN) != (ssize_t)fve_entries_size) {
-		log_err(cd, _("Failed to read BITLK metadata entries from %s."), device_path(device));
 		r = -EINVAL;
 		goto out;
 	}
 
+	/* fetch these entries from validated buffer to avoid double-fetch */
+	memcpy(fve_entries, fve_validated_block + BITLK_FVE_METADATA_HEADERS_LEN, fve_entries_size);
+
 	while ((fve_entries_size - start) >= (sizeof(entry_size) + sizeof(entry_type))) {
 
 		/* size of this entry */
@@ -716,6 +860,8 @@ int BITLK_read_sb(struct crypt_device *cd, struct bitlk_metadata *params)
 	}
 out:
 	free(fve_entries);
+	free(fve_validated_block);
+
 	return r;
 }
 
@@ -982,9 +1128,13 @@ static int bitlk_kdf(const char *password,
 	struct crypt_hash *hd = NULL;
 	int len = 0;
 	char16_t *utf16Password = NULL;
+	size_t utf16Len = 0;
 	int i = 0;
 	int r = 0;
 
+	if (!password)
+		return -EINVAL;
+
 	memcpy(kdf.salt, salt, 16);
 
 	r = crypt_hash_init(&hd, BITLK_KDF_HASH);
@@ -1007,7 +1157,8 @@ static int bitlk_kdf(const char *password,
 		if (r < 0)
 			goto out;
 
-		crypt_hash_write(hd, (char*)utf16Password, passwordLen * 2);
+		utf16Len = crypt_char16_strlen(utf16Password);
+		crypt_hash_write(hd, (char*)utf16Password, utf16Len * 2);
 		r = crypt_hash_final(hd, kdf.initial_sha256, len);
 		if (r < 0)
 			goto out;
@@ -1098,6 +1249,41 @@ out:
 	return r;
 }
 
+static int get_clear_key(struct crypt_device *cd, const struct bitlk_vmk *vmk, struct volume_key **vmk_dec_key)
+{
+	struct volume_key *nested_key = vmk->vk;
+
+	if (!nested_key) {
+		log_dbg(cd, "Clearkey VMK structure incomplete - missing nested key");
+		return -ENOTSUP;
+	}
+
+	struct volume_key *encrypted_vmk = crypt_volume_key_next(nested_key);
+
+	if (!encrypted_vmk) {
+		log_dbg(cd, "Clearkey VMK structure incomplete - missing encrypted VMK");
+		return -ENOTSUP;
+	}
+
+	/**
+	 *  For clearkey protection, we need to decrypt the encrypted VMK using the nested key
+	 *  and return the decrypted VMK as vmk_dec_key
+	 */
+	struct volume_key *decrypted_vmk = NULL;
+	int r = decrypt_key(cd, &decrypted_vmk, encrypted_vmk, nested_key,
+			vmk->mac_tag, BITLK_VMK_MAC_TAG_SIZE,
+			vmk->nonce, BITLK_NONCE_SIZE, false);
+
+	if (r == 0 && decrypted_vmk) {
+		log_dbg(cd, "Successfully decrypted VMK using nested key");
+		*vmk_dec_key = decrypted_vmk;
+		return 0;
+	} else {
+		log_dbg(cd, "Failed to decrypt VMK using nested key (error: %d)", r);
+		return r;
+	}
+}
+
 int BITLK_get_volume_key(struct crypt_device *cd,
 			 const char *password,
 			 size_t passwordLen,
@@ -1108,10 +1294,12 @@ int BITLK_get_volume_key(struct crypt_device *cd,
 	struct volume_key *open_vmk_key = NULL;
 	struct volume_key *vmk_dec_key = NULL;
 	struct volume_key *recovery_key = NULL;
+	struct bitlk_validation_hash dec_hash = {};
 	const struct bitlk_vmk *next_vmk = NULL;
 
 	next_vmk = params->vmks;
 	while (next_vmk) {
+		bool is_decrypted = false;
 		if (next_vmk->protection == BITLK_PROTECTION_PASSPHRASE) {
 			r = bitlk_kdf(password, passwordLen, false, next_vmk->salt, &vmk_dec_key);
 			if (r) {
@@ -1146,8 +1334,18 @@ int BITLK_get_volume_key(struct crypt_device *cd,
 				continue;
 			}
 			log_dbg(cd, "Trying to use external key found in provided password.");
+		} else if (next_vmk->protection == BITLK_PROTECTION_CLEAR_KEY) {
+			r = get_clear_key(cd, next_vmk, &vmk_dec_key);
+			if (r) {
+				/* something wrong happened, but we still want to check other key slots */
+				next_vmk = next_vmk->next;
+				continue;
+			}
+			is_decrypted = true;
+			open_vmk_key = vmk_dec_key;
+			log_dbg(cd, "Extracted VMK using clearkey.");
 		} else {
-			/* only passphrase, recovery passphrase and startup key VMKs supported right now */
+			/* only passphrase, recovery passphrase, startup key and clearkey VMKs supported right now */
 			log_dbg(cd, "Skipping %s", get_vmk_protection_string(next_vmk->protection));
 			next_vmk = next_vmk->next;
 			if (r == 0)
@@ -1156,19 +1354,51 @@ int BITLK_get_volume_key(struct crypt_device *cd,
 			continue;
 		}
 
-		log_dbg(cd, "Trying to decrypt %s.", get_vmk_protection_string(next_vmk->protection));
+		if (!is_decrypted) {
-		r = decrypt_key(cd, &open_vmk_key, next_vmk->vk, vmk_dec_key,
+			r = decrypt_key(cd, &open_vmk_key, next_vmk->vk, vmk_dec_key,
-				next_vmk->mac_tag, BITLK_VMK_MAC_TAG_SIZE,
+					next_vmk->mac_tag, BITLK_VMK_MAC_TAG_SIZE,
-				next_vmk->nonce, BITLK_NONCE_SIZE, false);
+					next_vmk->nonce, BITLK_NONCE_SIZE, false);
+
+			crypt_free_volume_key(vmk_dec_key);
+		}
 		if (r < 0) {
 			log_dbg(cd, "Failed to decrypt VMK using provided passphrase.");
-			crypt_free_volume_key(vmk_dec_key);
+
 			if (r == -ENOTSUP)
 				return r;
 			next_vmk = next_vmk->next;
 			continue;
 		}
-		crypt_free_volume_key(vmk_dec_key);
+
+		log_dbg(cd, "Trying to decrypt validation metadata using VMK.");
+		r = crypt_bitlk_decrypt_key(crypt_volume_key_get_key(open_vmk_key),
+			crypt_volume_key_length(open_vmk_key),
+			(const char*)params->validation->enc_datum,
+			(char *)&dec_hash,
+			BITLK_VALIDATION_VMK_DATA_SIZE - BITLK_NONCE_SIZE - BITLK_VMK_MAC_TAG_SIZE,
+			(const char*)params->validation->nonce, BITLK_NONCE_SIZE,
+			(const char*)params->validation->mac_tag, BITLK_VMK_MAC_TAG_SIZE);
+		if (r < 0) {
+			log_dbg(cd, "Failed to decrypt validation metadata using VMK.");
+			crypt_free_volume_key(open_vmk_key);
+			if (r == -ENOTSUP)
+				return r;
+			break;
+		}
+
+		/* now, do the MAC validation */
+		if (le16_to_cpu(dec_hash.role) != 0 ||le16_to_cpu(dec_hash.type) != 1 ||
+			(le16_to_cpu(dec_hash.hash_type) != 0x2005)) {
+			log_dbg(cd, "Failed to parse decrypted validation metadata.");
+			crypt_free_volume_key(open_vmk_key);
+			return -ENOTSUP;
+		}
+
+		if (memcmp(dec_hash.hash, params->sha256_fve, sizeof(dec_hash.hash)) != 0) {
+			log_dbg(cd, "Failed MAC validation of BITLK FVE metadata.");
+			crypt_free_volume_key(open_vmk_key);
+			return -EINVAL;
+		}
 
 		r = decrypt_key(cd, open_fvek_key, params->fvek->vk, open_vmk_key,
 				params->fvek->mac_tag, BITLK_VMK_MAC_TAG_SIZE,
@@ -1197,8 +1427,6 @@ int BITLK_get_volume_key(struct crypt_device *cd,
 static int _activate_check(struct crypt_device *cd,
 		           const struct bitlk_metadata *params)
 {
-	const struct bitlk_vmk *next_vmk = NULL;
-
 	if (!params->state) {
 		log_err(cd, _("This BITLK device is in an unsupported state and cannot be activated."));
 		return -ENOTSUP;
@@ -1209,15 +1437,6 @@ static int _activate_check(struct crypt_device *cd,
 		return -ENOTSUP;
 	}
 
-	next_vmk = params->vmks;
-	while (next_vmk) {
-		if (next_vmk->protection == BITLK_PROTECTION_CLEAR_KEY) {
-			log_err(cd, _("Activation of BITLK device with clear key protection is not supported."));
-			return -ENOTSUP;
-		}
-		next_vmk = next_vmk->next;
-	}
-
 	return 0;
 }
 

lib/bitlk/bitlk.h

@@ -21,6 +21,8 @@ struct volume_key;
 #define BITLK_NONCE_SIZE 12
 #define BITLK_SALT_SIZE 16
 #define BITLK_VMK_MAC_TAG_SIZE 16
+#define BITLK_VALIDATION_VMK_HEADER_SIZE 8
+#define BITLK_VALIDATION_VMK_DATA_SIZE 72
 
 #define BITLK_STATE_NORMAL 0x0004
 
@@ -85,6 +87,13 @@ struct bitlk_fvek {
 	struct volume_key *vk;
 };
 
+struct bitlk_validation {
+	uint8_t mac_tag[BITLK_VMK_MAC_TAG_SIZE];
+	uint8_t nonce[BITLK_NONCE_SIZE];
+	/* technically, this is not "VMK", but some sources call it this way */
+	uint8_t enc_datum[BITLK_VALIDATION_VMK_DATA_SIZE];
+};
+
 struct bitlk_metadata {
 	uint16_t sector_size;
 	uint64_t volume_size;
@@ -101,8 +110,10 @@ struct bitlk_metadata {
 	uint32_t metadata_version;
 	uint64_t volume_header_offset;
 	uint64_t volume_header_size;
+	const char *sha256_fve[32];
 	struct bitlk_vmk *vmks;
 	struct bitlk_fvek *fvek;
+	struct bitlk_validation *validation;
 };
 
 int BITLK_read_sb(struct crypt_device *cd, struct bitlk_metadata *params);

lib/crypto_backend/base64.c

@@ -19,7 +19,7 @@
 /* https://tools.ietf.org/html/rfc4648#section-4 */
 static char base64char(int x)
 {
-	static const char table[64] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+	static const char table[65] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
 				      "abcdefghijklmnopqrstuvwxyz"
 				      "0123456789+/";
 	return table[x & 63];

lib/crypto_backend/cipher_generic.c

@@ -8,6 +8,8 @@
 
 #include <errno.h>
 #include <strings.h>
+#include <unistd.h>
+#include <fcntl.h>
 #include "crypto_backend.h"
 
 struct cipher_alg {
@@ -77,3 +79,21 @@ int crypt_cipher_wrapped_key(const char *name, const char *mode)
 
 	return ca ? (int)ca->wrapped_key : 0;
 }
+
+bool crypt_fips_mode_kernel(void)
+{
+	int fd;
+	char buf = 0;
+
+	fd = open("/proc/sys/crypto/fips_enabled", O_RDONLY);
+
+	if (fd < 0)
+		return false;
+
+	if (read(fd, &buf, 1) != 1)
+		buf = '0';
+
+	close(fd);
+
+	return (buf == '1');
+}

lib/crypto_backend/crypto_backend.h

@@ -30,7 +30,7 @@ struct crypt_hmac;
 struct crypt_cipher;
 struct crypt_storage;
 
-int crypt_backend_init(bool fips);
+int crypt_backend_init(void);
 void crypt_backend_destroy(void);
 
 #define CRYPT_BACKEND_KERNEL     (1 << 0) /* Crypto uses kernel part, for benchmark */
@@ -93,6 +93,7 @@ int crypt_base64_decode(char **out, size_t *out_length, const char *in, size_t i
 /* UTF8/16 */
 int crypt_utf16_to_utf8(char **out, const char16_t *s, size_t length /* bytes! */);
 int crypt_utf8_to_utf16(char16_t **out, const char *s, size_t length);
+size_t crypt_char16_strlen(const char16_t *s);
 
 /* Block ciphers */
 int crypt_cipher_ivsize(const char *name, const char *mode);
@@ -147,6 +148,9 @@ int crypt_backend_memeq(const void *m1, const void *m2, size_t n);
 /* crypto backend running in FIPS mode */
 bool crypt_fips_mode(void);
 
+/* kernel running in FIPS mode */
+bool crypt_fips_mode_kernel(void);
+
 # ifdef __cplusplus
 }
 # endif

lib/crypto_backend/crypto_cipher_kernel.c

@@ -99,6 +99,20 @@ int crypt_cipher_init_kernel(struct crypt_cipher_kernel *ctx, const char *name,
 	return _crypt_cipher_init(ctx, key, key_length, 0, &sa);
 }
 
+/* musl has broken CMSG_NXTHDR macro in system headers */
+static inline struct cmsghdr *_CMSG_NXTHDR(struct msghdr* mhdr, struct cmsghdr* cmsg)
+{
+#if !defined(__GLIBC__) && defined(__clang__)
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wcast-align"
+#pragma clang diagnostic ignored "-Wsign-compare"
+	return CMSG_NXTHDR(mhdr, cmsg);
+#pragma clang diagnostic pop
+#else
+	return CMSG_NXTHDR(mhdr, cmsg);
+#endif
+}
+
 /* The in/out should be aligned to page boundary */
 /* coverity[ -taint_source : arg-3 ] */
 static int _crypt_cipher_crypt(struct crypt_cipher_kernel *ctx,
@@ -146,7 +160,7 @@ static int _crypt_cipher_crypt(struct crypt_cipher_kernel *ctx,
 
 	/* Set IV */
 	if (iv) {
-		header = CMSG_NXTHDR(&msg, header);
+		header = _CMSG_NXTHDR(&msg, header);
 		if (!header)
 			return -EINVAL;
 

lib/crypto_backend/crypto_gcrypt.c

@@ -80,7 +80,7 @@ static void crypt_hash_test_whirlpool_bug(void)
 		crypto_backend_whirlpool_bug = 1;
 }
 
-int crypt_backend_init(bool fips __attribute__((unused)))
+int crypt_backend_init(void)
 {
 	int r;
 
@@ -684,7 +684,7 @@ bool crypt_fips_mode(void)
 	if (fips_checked)
 		return fips_mode;
 
-	if (crypt_backend_init(false /* ignored */))
+	if (crypt_backend_init())
 		return false;
 
 	fips_mode = gcry_fips_mode_active();

lib/crypto_backend/crypto_kernel.c

@@ -103,7 +103,7 @@ static int crypt_kernel_socket_init(struct sockaddr_alg *sa, int *tfmfd, int *op
 	return 0;
 }
 
-int crypt_backend_init(bool fips __attribute__((unused)))
+int crypt_backend_init(void)
 {
 	struct utsname uts;
 	struct sockaddr_alg sa = {
@@ -408,5 +408,5 @@ int crypt_backend_memeq(const void *m1, const void *m2, size_t n)
 
 bool crypt_fips_mode(void)
 {
-	return false;
+	return crypt_fips_mode_kernel();
 }

lib/crypto_backend/crypto_mbedtls.c

@@ -69,16 +69,13 @@ static const mbedtls_md_info_t *crypt_get_hash(const char *name)
 	return NULL;
 }
 
-int crypt_backend_init(bool fips)
+int crypt_backend_init(void)
 {
 	int ret;
 
 	if (g_initialized)
 		return 0;
 
-	if (fips)
-		return -ENOTSUP;
-
 	mbedtls_version_get_string_full(g_backend_version);
 
 	mbedtls_entropy_init(&g_entropy);

lib/crypto_backend/crypto_nettle.c

@@ -200,7 +200,7 @@ static struct hash_alg *_get_alg(const char *name)
 	return NULL;
 }
 
-int crypt_backend_init(bool fips __attribute__((unused)))
+int crypt_backend_init(void)
 {
 	return 0;
 }

lib/crypto_backend/crypto_nss.c

@@ -62,7 +62,7 @@ static struct hash_alg *_get_alg(const char *name)
 	return NULL;
 }
 
-int crypt_backend_init(bool fips __attribute__((unused)))
+int crypt_backend_init(void)
 {
 	int r;
 

lib/crypto_backend/crypto_openssl.c

@@ -205,12 +205,12 @@ static const char *openssl_backend_version(void)
 }
 #endif
 
-int crypt_backend_init(bool fips)
+int crypt_backend_init(void)
 {
 	if (crypto_backend_initialised)
 		return 0;
 
-	if (openssl_backend_init(fips))
+	if (openssl_backend_init(crypt_fips_mode()))
 		return -EINVAL;
 
 	crypto_backend_initialised = 1;

lib/crypto_backend/memutils.c

@@ -9,11 +9,9 @@
 
 #define ATTR_NOINLINE __attribute__ ((noinline))
 #define ATTR_ZERO_REGS
-#if defined __has_attribute
+#if HAVE_ATTRIBUTE_ZEROCALLUSEDREGS
-#  if __has_attribute (zero_call_used_regs)
 #    undef ATTR_ZERO_REGS
 #    define ATTR_ZERO_REGS __attribute__ ((zero_call_used_regs("used")))
-#  endif
 #endif
 
 /* Workaround for https://github.com/google/sanitizers/issues/1507 */

lib/crypto_backend/utf8.c

@@ -274,3 +274,20 @@ int crypt_utf8_to_utf16(char16_t **out, const char *s, size_t length)
 	*p = 0;
 	return 0;
 }
+
+/**
+ * crypt_char16_strlen()
+ * @s: string to get length of
+ *
+ * Returns: number of 16-bit words in the string
+ */
+size_t crypt_char16_strlen(const char16_t *s) {
+	size_t n = 0;
+
+	assert(s);
+
+	while (*s != 0)
+		n++, s++;
+
+	return n;
+}

lib/integrity/integrity.c

@@ -151,6 +151,12 @@ int INTEGRITY_key_size(const char *integrity, int required_key_size)
 		ks = required_key_size ?: 32;
 	else if (!strcmp(integrity, "hmac(sha512)"))
 		ks = required_key_size ?: 64;
+	else if (!strcmp(integrity, "phmac(sha1)"))
+		ks = required_key_size ?: -EINVAL;
+	else if (!strcmp(integrity, "phmac(sha256)"))
+		ks = required_key_size ?: -EINVAL;
+	else if (!strcmp(integrity, "phmac(sha512)"))
+		ks = required_key_size ?: -EINVAL;
 	else if (!strcmp(integrity, "poly1305"))
 		ks = 0;
 	else if (!strcmp(integrity, "none"))
@@ -180,6 +186,8 @@ int INTEGRITY_hash_tag_size(const char *integrity)
 		return 8;
 
 	r = sscanf(integrity, "hmac(%" MAX_CIPHER_LEN_STR "[^)]s", hash);
+	if (r != 1)
+		r = sscanf(integrity, "phmac(%" MAX_CIPHER_LEN_STR "[^)]s", hash);
 	if (r == 1)
 		r = crypt_hash_size(hash);
 	else
@@ -222,6 +230,12 @@ int INTEGRITY_tag_size(const char *integrity,
 		auth_tag_size = 32;
 	else if (!strcmp(integrity, "hmac(sha512)"))
 		auth_tag_size = 64;
+	else if (!strcmp(integrity, "phmac(sha1)"))
+		auth_tag_size = 20;
+	else if (!strcmp(integrity, "phmac(sha256)"))
+		auth_tag_size = 32;
+	else if (!strcmp(integrity, "phmac(sha512)"))
+		auth_tag_size = 64;
 	else if (!strcmp(integrity, "poly1305")) {
 		if (iv_tag_size)
 			iv_tag_size = 12;

lib/keyslot_context.c

@@ -479,7 +479,7 @@ static int get_luks1_volume_key_by_keyring(struct crypt_device *cd,
 	int r;
 
 	assert(cd);
-	assert(kc && kc->type == CRYPT_KC_TYPE_PASSPHRASE);
+	assert(kc && kc->type == CRYPT_KC_TYPE_KEYRING);
 	assert(r_vk);
 
 	r = get_passphrase_by_keyring(cd, kc, CONST_CAST(const char **) &kc->i_passphrase,

lib/libcryptsetup.h

@@ -980,7 +980,7 @@ int crypt_resume_by_keyfile(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param name name of device to resume
  * @param volume_key provided volume key
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  *
  * @return @e 0 on success or negative errno value otherwise.
  */
@@ -1152,7 +1152,7 @@ int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
  * @param volume_key provided volume key or @e NULL if used after crypt_format
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param passphrase passphrase for new keyslot
  * @param passphrase_size size of passphrase
  *
@@ -1182,7 +1182,7 @@ int crypt_keyslot_add_by_volume_key(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
  * @param volume_key provided volume key or @e NULL (see note below)
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param passphrase passphrase for new keyslot
  * @param passphrase_size size of passphrase
  * @param flags key flags to set
@@ -1289,7 +1289,7 @@ int crypt_keyslot_context_init_by_token(struct crypt_device *cd,
  *
  * @param volume_key provided volume key or @e NULL if used after crypt_format
  *        or with CRYPT_VOLUME_KEY_NO_SEGMENT flag
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_KEY
  *
  * @return zero on success or negative errno otherwise.
@@ -1305,9 +1305,9 @@ int crypt_keyslot_context_init_by_volume_key(struct crypt_device *cd,
  * @param cd crypt device handle initialized to device context
  *
  * @param volume_key provided volume key
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param signature buffer with signature for the key
- * @param signature_size bsize of signature buffer
+ * @param signature_size size of signature buffer
  * @param kc returns crypt keyslot context handle type CRYPT_KC_TYPE_SIGNED_KEY
  *
  * @return zero on success or negative errno otherwise.
@@ -1753,7 +1753,7 @@ int crypt_activate_by_keyfile(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param name name of device to create, if @e NULL only check volume key
  * @param volume_key provided volume key (or @e NULL to use internal)
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param flags activation flags
  *
  * @return @e 0 on success or negative errno value otherwise.
@@ -1782,9 +1782,9 @@ int crypt_activate_by_volume_key(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param name name of device to create
  * @param volume_key provided volume key
- * @param volume_key_size size of volume_key
+ * @param volume_key_size size of volume_key in bytes
  * @param signature buffer with signature for the key
- * @param signature_size bsize of signature buffer
+ * @param signature_size size of signature buffer
  * @param flags activation flags
  *
  * @return @e 0 on success or negative errno value otherwise.
@@ -1865,7 +1865,7 @@ int crypt_deactivate(struct crypt_device *cd, const char *name);
  * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
  * @param volume_key buffer for volume key
  * @param volume_key_size on input, size of buffer @e volume_key,
- *        on output size of @e volume_key
+ *        on output size of @e volume_key in bytes
  * @param passphrase passphrase used to unlock volume key
  * @param passphrase_size size of @e passphrase
  *
@@ -1892,7 +1892,7 @@ int crypt_volume_key_get(struct crypt_device *cd,
  * @param keyslot use this keyslot or @e CRYPT_ANY_SLOT
  * @param volume_key buffer for volume key
  * @param volume_key_size on input, size of buffer @e volume_key,
- *        on output size of @e volume_key
+ *        on output size of @e volume_key in bytes
  * @param kc keyslot context used to unlock volume key
  *
  * @return unlocked key slot number or negative errno otherwise.
@@ -1925,7 +1925,7 @@ int crypt_volume_key_get_by_keyslot_context(struct crypt_device *cd,
  *
  * @param cd crypt device handle
  * @param volume_key provided volume key
- * @param volume_key_size size of @e volume_key
+ * @param volume_key_size size of @e volume_key in bytes
  *
  * @return @e 0 on success or negative errno value otherwise.
  *
@@ -2117,6 +2117,18 @@ int crypt_header_is_detached(struct crypt_device *cd);
 int crypt_get_verity_info(struct crypt_device *cd,
 	struct crypt_params_verity *vp);
 
+/**
+ * Get FEC repaired block count for VERITY device.
+ *
+ * @param cd crypt device handle
+ * @param name verity device name
+ * @param repaired FEC repaired blocks
+ *
+ * @return @e 0 on success or negative errno value otherwise.
+ */
+int crypt_get_verity_repaired(struct crypt_device *cd, const char *name,
+			      uint64_t *repaired);
+
 /**
  * Get device parameters for INTEGRITY device.
  *
@@ -2172,7 +2184,7 @@ int crypt_benchmark(struct crypt_device *cd,
  * @param password_size size of password
  * @param salt salt for benchmark
  * @param salt_size size of salt
- * @param volume_key_size output volume key size
+ * @param volume_key_size output volume key size in bytes
  * @param progress callback function
  * @param usrptr provided identification in callback
  *
@@ -2409,8 +2421,8 @@ void crypt_set_debug_level(int level);
  * @param cd crypt device handle
  * @param keyfile keyfile to read
  * @param key buffer for key
- * @param key_size_read size of read key
+ * @param key_size_read size of read key in bytes
- * @param keyfile_offset key offset in keyfile
+ * @param keyfile_offset key offset in bytes in keyfile
  * @param key_size exact key length to read from file or 0
  * @param flags keyfile read flags
  *

lib/libcryptsetup.sym

@@ -195,3 +195,8 @@ CRYPTSETUP_2.8 {
 		crypt_get_old_volume_key_size;
 		crypt_format_inline;
 } CRYPTSETUP_2.7;
+
+CRYPTSETUP_2.9 {
+	global:
+		crypt_get_verity_repaired;
+} CRYPTSETUP_2.8;

lib/libdevmapper.c

@@ -1992,6 +1992,40 @@ int dm_status_verity_ok(struct crypt_device *cd, const char *name)
 	return r;
 }
 
+int dm_status_verity_repaired(struct crypt_device *cd, const char *name, uint64_t *repaired)
+{
+	int r;
+	struct dm_info dmi;
+	char *status_line = NULL, *p;
+	uint64_t val64;
+
+	if (dm_init_context(cd, DM_VERITY))
+		return -ENOTSUP;
+
+	r = dm_status_dmi(name, &dmi, DM_VERITY_TARGET, &status_line);
+	dm_exit_context();
+	if (r < 0 || !status_line || !*status_line) {
+		free(status_line);
+		return r;
+	}
+	p = status_line + 1;
+	while (*p == ' ')
+		p++;
+
+	if (!*p || *p == '-' || sscanf(p, "%" PRIu64, &val64) != 1) {
+		free(status_line);
+		return -ENOTSUP;
+	}
+
+	log_dbg(cd, "Verity volume %s status is %s.", name, status_line ?: "");
+
+	if (repaired)
+		*repaired = val64;
+
+	free(status_line);
+	return 0;
+}
+
 int dm_status_integrity_failures(struct crypt_device *cd, const char *name, uint64_t *count)
 {
 	int r;

lib/luks2/hw_opal/hw_opal.c

@@ -58,6 +58,12 @@ typedef enum OpalStatus {
 	_OPAL_STATUS_MAX = 0x13,
 } OpalStatus;
 
+/*
+ * Also defined in TCG Core spec Section 5.1.5 but
+ * do not inflate the opal_status_table below
+ */
+#define  OPAL_STATUS_FAIL 0x3f
+
 static const char* const opal_status_table[_OPAL_STATUS_MAX] = {
 	[OPAL_STATUS_SUCCESS]               = "success",
 	[OPAL_STATUS_NOT_AUTHORIZED]        = "not authorized",
@@ -85,9 +91,9 @@ static const char *opal_status_to_string(int t)
 	if (t < 0)
 		return strerror(-t);
 
-	/* Fail, as defined by specification */
+	/* This will be checked upon 'Reactivate' method */
-	if (t == 0x3f)
+	if (t == OPAL_STATUS_FAIL)
-		return "unknown failure";
+		return "FAIL status";
 
 	if (t >= _OPAL_STATUS_MAX)
 		return "unknown error";
@@ -236,6 +242,8 @@ static int opal_ioctl(struct crypt_device *cd, int fd, unsigned long rq, void *a
 
 	opal_ioctl_debug(cd, rq, args, false, 0);
 	r = ioctl(fd, rq, args);
+	if (r < 0)
+		r = -errno;
 	opal_ioctl_debug(cd, rq, args, true, r);
 
 	return r;
@@ -396,6 +404,194 @@ static int opal_enabled(struct crypt_device *cd, struct device *dev)
 	return opal_query_status(cd, dev, OPAL_FL_LOCKING_ENABLED);
 }
 
+static int opal_activate_lsp(struct crypt_device *cd, int fd,
+			     const void *admin_key, size_t admin_key_len)
+{
+	int r;
+	struct opal_lr_act *activate = crypt_safe_alloc(sizeof(*activate));
+
+	if (!activate)
+		return -ENOMEM;
+
+	*activate = (struct opal_lr_act) {
+		.key = {
+			.key_len = admin_key_len,
+		},
+		/* useless but due to kernel bug it requires (num_lrs > 0 && num_lrs <= 9) */
+		.num_lrs = 1,
+	};
+	crypt_safe_memcpy(activate->key.key, admin_key, admin_key_len);
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_TAKE_OWNERSHIP, &activate->key);
+	if (r < 0) {
+		r = -ENOTSUP;
+		log_dbg(cd, "OPAL not supported on this kernel version, refusing.");
+		goto out;
+	}
+	if (r == OPAL_STATUS_NOT_AUTHORIZED) /* We'll try again with a different key. */ {
+		r = -EPERM;
+		log_dbg(cd, "Failed to take ownership of OPAL device '%s': permission denied",
+			crypt_get_device_name(cd));
+		goto out;
+	}
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to take ownership of OPAL device '%s': %s",
+			crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+		goto out;
+	}
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_ACTIVATE_LSP, activate);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to activate OPAL device '%s': %s",
+			crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+	}
+out:
+	crypt_safe_free(activate);
+
+	return r;
+}
+
+static int opal_reuse_active_lsp(struct crypt_device *cd, int fd,
+			   uint32_t segment_number,
+			   const void *admin_key, size_t admin_key_len)
+{
+	int r;
+	struct opal_session_info *user_session = crypt_safe_alloc(sizeof(*user_session));
+
+	if (!user_session)
+		return -ENOMEM;
+
+	*user_session = (struct opal_session_info) {
+		.who = OPAL_ADMIN1, /* irrelevant in SUM */
+		.opal_key = {
+			.lr = segment_number,
+			.key_len = admin_key_len,
+		},
+	};
+
+	/* If it is already enabled, wipe the locking range first */
+	crypt_safe_memcpy(user_session->opal_key.key, admin_key, admin_key_len);
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_SECURE_ERASE_LR, user_session);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to reset (secure erase) OPAL locking range %u on device '%s': %s",
+			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+	}
+out:
+	crypt_safe_free(user_session);
+
+	return r;
+}
+
+static int opal_setup_range(struct crypt_device *cd, int fd, uint32_t segment_number,
+			    uint64_t range_start_blocks, uint64_t range_length_blocks,
+			    const void *admin_key, size_t admin_key_len)
+{
+	int r;
+	struct opal_user_lr_setup *setup = crypt_safe_alloc(sizeof(*setup));
+
+	if (!setup)
+		return -ENOMEM;
+
+	*setup = (struct opal_user_lr_setup) {
+		.range_start = range_start_blocks,
+		.range_length = range_length_blocks,
+		/* Some drives do not enable Locking Ranges on setup. This have some
+		 * interesting consequences: Lock command called later below will pass,
+		 * but locking range will _not_ be locked at all.
+		 */
+		.RLE = 1,
+		.WLE = 1,
+		.session = {
+			.who = OPAL_ADMIN1,
+			.opal_key = {
+				.key_len = admin_key_len,
+				.lr = segment_number,
+			},
+		},
+	};
+	crypt_safe_memcpy(setup->session.opal_key.key, admin_key, admin_key_len);
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_LR_SETUP, setup);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to setup locking range of length %llu at offset %llu on OPAL device '%s': %s",
+			setup->range_length, setup->range_start, crypt_get_device_name(cd),
+			opal_status_to_string(r));
+		r = -EINVAL;
+	}
+out:
+	crypt_safe_free(setup);
+
+	return r;
+}
+
+static int opal_setup_user(struct crypt_device *cd, int fd, uint32_t segment_number,
+			   const void *admin_key, size_t admin_key_len)
+{
+	int r;
+	struct opal_lock_unlock *user_add_to_lr = crypt_safe_alloc(sizeof(*user_add_to_lr));
+
+	if (!user_add_to_lr)
+		return -ENOMEM;
+
+	*user_add_to_lr = (struct opal_lock_unlock) {
+		.session = {
+			.who = segment_number + 1,
+			.opal_key = {
+				.lr = segment_number,
+				.key_len = admin_key_len,
+			},
+		},
+		.l_state = OPAL_RO,
+	};
+
+	crypt_safe_memcpy(user_add_to_lr->session.opal_key.key, admin_key, admin_key_len);
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_ACTIVATE_USR, &user_add_to_lr->session);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to activate OPAL user on device '%s': %s",
+			crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+		goto out;
+	}
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_ADD_USR_TO_LR, user_add_to_lr);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to add OPAL user to locking range %u (RO) on device '%s': %s",
+			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+		goto out;
+	}
+
+	user_add_to_lr->l_state = OPAL_RW;
+
+	r = opal_ioctl(cd, fd, IOC_OPAL_ADD_USR_TO_LR, user_add_to_lr);
+	if (r < 0)
+		goto out;
+	if (r != OPAL_STATUS_SUCCESS) {
+		log_dbg(cd, "Failed to add OPAL user to locking range %u (RW) on device '%s': %s",
+			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
+		r = -EINVAL;
+	}
+out:
+	crypt_safe_free(user_add_to_lr);
+
+	return r;
+}
+
 /* requires opal lock */
 int opal_setup_ranges(struct crypt_device *cd,
 		      struct device *dev,
@@ -407,11 +603,8 @@ int opal_setup_ranges(struct crypt_device *cd,
 		      const void *admin_key,
 		      size_t admin_key_len)
 {
-	struct opal_lr_act *activate = NULL;
+	struct opal_lock_unlock *lock = NULL;
-	struct opal_session_info *user_session = NULL;
-	struct opal_lock_unlock *user_add_to_lr = NULL, *lock = NULL;
 	struct opal_new_pw *new_pw = NULL;
-	struct opal_user_lr_setup *setup = NULL;
 	int r, fd;
 
 	assert(cd);
@@ -437,130 +630,16 @@ int opal_setup_ranges(struct crypt_device *cd,
 		return r;
 
 	/* If OPAL has never been enabled, we need to take ownership and do basic setup first */
-	if (r == 0) {
+	if (r == 0)
-		activate = crypt_safe_alloc(sizeof(struct opal_lr_act));
+		r = opal_activate_lsp(cd, fd, admin_key, admin_key_len);
-		if (!activate) {
+	else
-			r = -ENOMEM;
+		r = opal_reuse_active_lsp(cd, fd, segment_number, admin_key, admin_key_len);
-			goto out;
+	if (r < 0)
-		}
-		*activate = (struct opal_lr_act) {
-			.key = {
-				.key_len = admin_key_len,
-			},
-			.num_lrs = 8,
-			/* A max of 9 segments are supported, enable them all as there's no reason not to
-			 * (0 is whole-volume)
-			 */
-			.lr = { 1, 2, 3, 4, 5, 6, 7, 8 },
-		};
-		crypt_safe_memcpy(activate->key.key, admin_key, admin_key_len);
-
-		r = opal_ioctl(cd, fd, IOC_OPAL_TAKE_OWNERSHIP, &activate->key);
-		if (r < 0) {
-			r = -ENOTSUP;
-			log_dbg(cd, "OPAL not supported on this kernel version, refusing.");
-			goto out;
-		}
-		if (r == OPAL_STATUS_NOT_AUTHORIZED) /* We'll try again with a different key. */ {
-			r = -EPERM;
-			log_dbg(cd, "Failed to take ownership of OPAL device '%s': permission denied",
-				crypt_get_device_name(cd));
-			goto out;
-		}
-		if (r != OPAL_STATUS_SUCCESS) {
-			log_dbg(cd, "Failed to take ownership of OPAL device '%s': %s",
-				crypt_get_device_name(cd), opal_status_to_string(r));
-			r = -EINVAL;
-			goto out;
-		}
-
-		r = opal_ioctl(cd, fd, IOC_OPAL_ACTIVATE_LSP, activate);
-		if (r != OPAL_STATUS_SUCCESS) {
-			log_dbg(cd, "Failed to activate OPAL device '%s': %s",
-				crypt_get_device_name(cd), opal_status_to_string(r));
-			r = -EINVAL;
-			goto out;
-		}
-	} else {
-		/* If it is already enabled, wipe the locking range first */
-		user_session = crypt_safe_alloc(sizeof(struct opal_session_info));
-		if (!user_session) {
-			r = -ENOMEM;
-			goto out;
-		}
-		*user_session = (struct opal_session_info) {
-			.who = OPAL_ADMIN1,
-			.opal_key = {
-				.lr = segment_number,
-				.key_len = admin_key_len,
-			},
-		};
-		crypt_safe_memcpy(user_session->opal_key.key, admin_key, admin_key_len);
-
-		r = opal_ioctl(cd, fd, IOC_OPAL_SECURE_ERASE_LR, user_session);
-		if (r != OPAL_STATUS_SUCCESS) {
-			log_dbg(cd, "Failed to reset (secure erase) OPAL locking range %u on device '%s': %s",
-				segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
-			r = -EINVAL;
-			goto out;
-		}
-	}
-
-	crypt_safe_free(user_session);
-
-	user_session = crypt_safe_alloc(sizeof(struct opal_session_info));
-	if (!user_session) {
-		r = -ENOMEM;
 		goto out;
-	}
-	*user_session = (struct opal_session_info) {
-		.who = segment_number + 1,
-		.opal_key = {
-			.key_len = admin_key_len,
-		},
-	};
-	crypt_safe_memcpy(user_session->opal_key.key, admin_key, admin_key_len);
 
-	r = opal_ioctl(cd, fd, IOC_OPAL_ACTIVATE_USR, user_session);
+	r = opal_setup_user(cd, fd, segment_number, admin_key, admin_key_len);
-	if (r != OPAL_STATUS_SUCCESS) {
+	if (r < 0)
-		log_dbg(cd, "Failed to activate OPAL user on device '%s': %s",
-			crypt_get_device_name(cd), opal_status_to_string(r));
-		r = -EINVAL;
 		goto out;
-	}
-
-	user_add_to_lr = crypt_safe_alloc(sizeof(struct opal_lock_unlock));
-	if (!user_add_to_lr) {
-		r = -ENOMEM;
-		goto out;
-	}
-	*user_add_to_lr = (struct opal_lock_unlock) {
-		.session = {
-			.who = segment_number + 1,
-			.opal_key = {
-				.lr = segment_number,
-				.key_len = admin_key_len,
-			},
-		},
-		.l_state = OPAL_RO,
-	};
-	crypt_safe_memcpy(user_add_to_lr->session.opal_key.key, admin_key, admin_key_len);
-
-	r = opal_ioctl(cd, fd, IOC_OPAL_ADD_USR_TO_LR, user_add_to_lr);
-	if (r != OPAL_STATUS_SUCCESS) {
-		log_dbg(cd, "Failed to add OPAL user to locking range %u (RO) on device '%s': %s",
-			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
-		r = -EINVAL;
-		goto out;
-	}
-	user_add_to_lr->l_state = OPAL_RW;
-	r = opal_ioctl(cd, fd, IOC_OPAL_ADD_USR_TO_LR, user_add_to_lr);
-	if (r != OPAL_STATUS_SUCCESS) {
-		log_dbg(cd, "Failed to add OPAL user to locking range %u (RW) on device '%s': %s",
-			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
-		r = -EINVAL;
-		goto out;
-	}
 
 	new_pw = crypt_safe_alloc(sizeof(struct opal_new_pw));
 	if (!new_pw) {
@@ -588,6 +667,8 @@ int opal_setup_ranges(struct crypt_device *cd,
 	crypt_safe_memcpy(new_pw->session.opal_key.key, admin_key, admin_key_len);
 
 	r = opal_ioctl(cd, fd, IOC_OPAL_SET_PW, new_pw);
+	if (r < 0)
+		goto out;
 	if (r != OPAL_STATUS_SUCCESS) {
 		log_dbg(cd, "Failed to set OPAL user password on device '%s': (%d) %s",
 			crypt_get_device_name(cd), r, opal_status_to_string(r));
@@ -595,37 +676,10 @@ int opal_setup_ranges(struct crypt_device *cd,
 		goto out;
 	}
 
-	setup = crypt_safe_alloc(sizeof(struct opal_user_lr_setup));
+	r = opal_setup_range(cd, fd, segment_number, range_start_blocks, range_length_blocks,
-	if (!setup) {
+			     admin_key, admin_key_len);
-		r = -ENOMEM;
+	if (r < 0)
 		goto out;
-	}
-	*setup = (struct opal_user_lr_setup) {
-		.range_start = range_start_blocks,
-		.range_length = range_length_blocks,
-		/* Some drives do not enable Locking Ranges on setup. This have some
-		 * interesting consequences: Lock command called later below will pass,
-		 * but locking range will _not_ be locked at all.
-		 */
-		.RLE = 1,
-		.WLE = 1,
-		.session = {
-			.who = OPAL_ADMIN1,
-			.opal_key = {
-				.key_len = admin_key_len,
-				.lr = segment_number,
-			},
-		},
-	};
-	crypt_safe_memcpy(setup->session.opal_key.key, admin_key, admin_key_len);
-
-	r = opal_ioctl(cd, fd, IOC_OPAL_LR_SETUP, setup);
-	if (r != OPAL_STATUS_SUCCESS) {
-		log_dbg(cd, "Failed to setup locking range of length %llu at offset %llu on OPAL device '%s': %s",
-			setup->range_length, setup->range_start, crypt_get_device_name(cd), opal_status_to_string(r));
-		r = -EINVAL;
-		goto out;
-	}
 
 	/* After setup an OPAL device is unlocked, but the expectation with cryptsetup is that it needs
 	 * to be activated separately, so lock it immediately. */
@@ -648,6 +702,8 @@ int opal_setup_ranges(struct crypt_device *cd,
 			  crypt_volume_key_length(vk));
 
 	r = opal_ioctl(cd, fd, IOC_OPAL_LOCK_UNLOCK, lock);
+	if (r < 0)
+		goto out;
 	if (r != OPAL_STATUS_SUCCESS) {
 		log_dbg(cd, "Failed to lock OPAL device '%s': %s",
 			crypt_get_device_name(cd), opal_status_to_string(r));
@@ -661,11 +717,7 @@ int opal_setup_ranges(struct crypt_device *cd,
 					   &(uint64_t) {range_length_blocks * opal_block_bytes / SECTOR_SIZE},
 					   &(bool) {true}, &(bool){true}, NULL, NULL);
 out:
-	crypt_safe_free(activate);
-	crypt_safe_free(user_session);
-	crypt_safe_free(user_add_to_lr);
 	crypt_safe_free(new_pw);
-	crypt_safe_free(setup);
 	crypt_safe_free(lock);
 
 	return r;
@@ -737,6 +789,8 @@ static int opal_lock_unlock(struct crypt_device *cd,
 		unlock.flags = OPAL_SAVE_FOR_LOCK;
 
 	r = opal_ioctl(cd, fd, IOC_OPAL_SAVE, &unlock);
+	if (r < 0)
+		goto out;
 	if (r != OPAL_STATUS_SUCCESS) {
 		if (!lock)
 			log_std(cd, "Failed to prepare OPAL device '%s' for sleep resume, be aware before suspending: %s",
@@ -790,7 +844,11 @@ int opal_factory_reset(struct crypt_device *cd,
 	if (password_len > OPAL_KEY_MAX)
 		return -EINVAL;
 
-	fd = device_open(cd, dev, O_RDONLY);
+	/*
+	 * Submit PSID reset on R/W file descriptor so it
+	 * triggers blkid rescan after we close it.
+	 */
+	fd = device_open(cd, dev, O_RDWR);
 	if (fd < 0)
 		return -EIO;
 
@@ -860,6 +918,8 @@ int opal_reset_segment(struct crypt_device *cd,
 	}
 
 	r = opal_ioctl(cd, fd, IOC_OPAL_SECURE_ERASE_LR, user_session);
+	if (r < 0)
+		goto out;
 	if (r != OPAL_STATUS_SUCCESS) {
 		log_dbg(cd, "Failed to reset (secure erase) OPAL locking range %u on device '%s': %s",
 			segment_number, crypt_get_device_name(cd), opal_status_to_string(r));
@@ -883,6 +943,8 @@ int opal_reset_segment(struct crypt_device *cd,
 	};
 
 	r = opal_ioctl(cd, fd, IOC_OPAL_LR_SETUP, setup);
+	if (r < 0)
+		goto out;
 	if (r != OPAL_STATUS_SUCCESS) {
 		log_dbg(cd, "Failed to disable locking range on OPAL device '%s': %s",
 			crypt_get_device_name(cd), opal_status_to_string(r));

lib/luks2/luks2_disk_metadata.c

@@ -15,7 +15,7 @@ static json_object *parse_json_len(struct crypt_device *cd, const char *json_are
 			    uint64_t max_length, int *json_len)
 {
 	json_object *jobj;
-	struct json_tokener *jtok;
+	json_tokener *jtok;
 
 	 /* INT32_MAX is internal (json-c) json_tokener_parse_ex() limit */
 	if (!json_area || max_length > INT32_MAX)

lib/luks2/luks2_json_format.c

@@ -203,7 +203,7 @@ int LUKS2_generate_hdr(
 	uint32_t opal_segment_number,
 	uint32_t opal_key_size)
 {
-	struct json_object *jobj_segment, *jobj_keyslots, *jobj_segments, *jobj_config;
+	json_object *jobj_segment, *jobj_keyslots, *jobj_segments, *jobj_config;
 	uuid_t partitionUuid;
 	int r, digest;
 

lib/luks2/luks2_json_metadata.c

@@ -49,9 +49,9 @@ void JSON_DBG(struct crypt_device *cd, json_object *jobj, const char *desc)
 /*
  * JSON array helpers
  */
-struct json_object *LUKS2_array_jobj(struct json_object *array, const char *num)
+json_object *LUKS2_array_jobj(json_object *array, const char *num)
 {
-	struct json_object *jobj1;
+	json_object *jobj1;
 	int i;
 
 	for (i = 0; i < (int) json_object_array_length(array); i++) {
@@ -63,9 +63,9 @@ struct json_object *LUKS2_array_jobj(struct json_object *array, const char *num)
 	return NULL;
 }
 
-struct json_object *LUKS2_array_remove(struct json_object *array, const char *num)
+json_object *LUKS2_array_remove(json_object *array, const char *num)
 {
-	struct json_object *jobj1, *jobj_removing = NULL, *array_new;
+	json_object *jobj1, *jobj_removing = NULL, *array_new;
 	int i;
 
 	jobj_removing = LUKS2_array_jobj(array, num);
@@ -1272,7 +1272,11 @@ int LUKS2_hdr_uuid(struct crypt_device *cd, struct luks2_hdr *hdr, const char *u
 int LUKS2_hdr_labels(struct crypt_device *cd, struct luks2_hdr *hdr,
 		     const char *label, const char *subsystem, int commit)
 {
-	//FIXME: check if the labels are the same and skip this.
+	if ((label && strlen(label) >= LUKS2_LABEL_L) ||
+	    (subsystem && strlen(subsystem) >= LUKS2_LABEL_L)) {
+		log_err(cd, _("Label is too long."));
+		return -EINVAL;
+	}
 
 	memset(hdr->label, 0, LUKS2_LABEL_L);
 	if (label)

lib/luks2/luks2_keyslot.c

@@ -165,7 +165,7 @@ int LUKS2_keyslot_cipher_incompatible(struct crypt_device *cd, const char *ciphe
 {
 	char cipher[MAX_CIPHER_LEN], cipher_mode[MAX_CIPHER_LEN];
 
-	if (!cipher_spec || crypt_is_cipher_null(cipher_spec))
+	if (!cipher_spec)
 		return 1;
 
 	/*

lib/luks2/luks2_keyslot_luks2.c

@@ -336,6 +336,10 @@ static int luks2_keyslot_get_key(struct crypt_device *cd,
 	if (r < 0)
 		return r;
 
+	/* Allow only empty passphrase with null cipher */
+	if (crypt_is_cipher_null(cipher) && passwordLen)
+		return -EPERM;
+
 	if (!json_object_object_get_ex(jobj_area, "key_size", &jobj2))
 		return -EINVAL;
 	keyslot_key_len = json_object_get_int(jobj2);

lib/luks2/luks2_luks1_convert.c

@@ -45,11 +45,11 @@ out:
 	return r;
 }
 
-static int json_luks1_keyslot(const struct luks_phdr *hdr_v1, int keyslot, struct json_object **keyslot_object)
+static int json_luks1_keyslot(const struct luks_phdr *hdr_v1, int keyslot, json_object **keyslot_object)
 {
 	char *base64_str, cipher[LUKS_CIPHERNAME_L+LUKS_CIPHERMODE_L];
 	size_t base64_len;
-	struct json_object *keyslot_obj, *field, *jobj_kdf, *jobj_af, *jobj_area;
+	json_object *keyslot_obj, *field, *jobj_kdf, *jobj_af, *jobj_area;
 	uint64_t offset, area_size, length;
 	int r;
 
@@ -136,10 +136,10 @@ err:
 	return r;
 }
 
-static int json_luks1_keyslots(const struct luks_phdr *hdr_v1, struct json_object **keyslots_object)
+static int json_luks1_keyslots(const struct luks_phdr *hdr_v1, json_object **keyslots_object)
 {
 	int keyslot, r;
-	struct json_object *keyslot_obj, *field;
+	json_object *keyslot_obj, *field;
 
 	keyslot_obj = json_object_new_object();
 	if (!keyslot_obj)
@@ -165,11 +165,11 @@ static int json_luks1_keyslots(const struct luks_phdr *hdr_v1, struct json_objec
 	return 0;
 }
 
-static int json_luks1_segment(const struct luks_phdr *hdr_v1, struct json_object **segment_object)
+static int json_luks1_segment(const struct luks_phdr *hdr_v1, json_object **segment_object)
 {
 	const char *c;
 	char cipher[LUKS_CIPHERNAME_L+LUKS_CIPHERMODE_L];
-	struct json_object *segment_obj, *field;
+	json_object *segment_obj, *field;
 	uint64_t number;
 
 	segment_obj = json_object_new_object();
@@ -239,10 +239,10 @@ static int json_luks1_segment(const struct luks_phdr *hdr_v1, struct json_object
 	return 0;
 }
 
-static int json_luks1_segments(const struct luks_phdr *hdr_v1, struct json_object **segments_object)
+static int json_luks1_segments(const struct luks_phdr *hdr_v1, json_object **segments_object)
 {
 	int r;
-	struct json_object *segments_obj, *field;
+	json_object *segments_obj, *field;
 
 	segments_obj = json_object_new_object();
 	if (!segments_obj)
@@ -264,12 +264,12 @@ static int json_luks1_segments(const struct luks_phdr *hdr_v1, struct json_objec
 	return 0;
 }
 
-static int json_luks1_digest(const struct luks_phdr *hdr_v1, struct json_object **digest_object)
+static int json_luks1_digest(const struct luks_phdr *hdr_v1, json_object **digest_object)
 {
 	char keyslot_str[16], *base64_str;
 	int r, ks;
 	size_t base64_len;
-	struct json_object *digest_obj, *array, *field;
+	json_object *digest_obj, *array, *field;
 
 	digest_obj = json_object_new_object();
 	if (!digest_obj)
@@ -380,10 +380,10 @@ static int json_luks1_digest(const struct luks_phdr *hdr_v1, struct json_object
 	return 0;
 }
 
-static int json_luks1_digests(const struct luks_phdr *hdr_v1, struct json_object **digests_object)
+static int json_luks1_digests(const struct luks_phdr *hdr_v1, json_object **digests_object)
 {
 	int r;
-	struct json_object *digests_obj, *field;
+	json_object *digests_obj, *field;
 
 	digests_obj = json_object_new_object();
 	if (!digests_obj)
@@ -400,10 +400,10 @@ static int json_luks1_digests(const struct luks_phdr *hdr_v1, struct json_object
 	return 0;
 }
 
-static int json_luks1_object(struct luks_phdr *hdr_v1, struct json_object **luks1_object, uint64_t keyslots_size)
+static int json_luks1_object(struct luks_phdr *hdr_v1, json_object **luks1_object, uint64_t keyslots_size)
 {
 	int r;
-	struct json_object *luks1_obj, *field;
+	json_object *luks1_obj, *field;
 	uint64_t json_size;
 
 	luks1_obj = json_object_new_object();

lib/luks2/luks2_reencrypt.c

@@ -34,7 +34,7 @@ struct luks2_reencrypt {
 
 	/* already running reencryption */
 	json_object *jobj_segs_hot;
-	struct json_object *jobj_segs_post;
+	json_object *jobj_segs_post;
 
 	/* backup segments */
 	json_object *jobj_segment_new;
@@ -54,6 +54,8 @@ struct luks2_reencrypt {
 	uint32_t wflags1;
 	uint32_t wflags2;
 
+	struct device *hotzone_device;
+
 	struct crypt_lock_handle *reenc_lock;
 };
 #if USE_LUKS2_REENCRYPTION
@@ -882,6 +884,8 @@ void LUKS2_reencrypt_free(struct crypt_device *cd, struct luks2_reencrypt *rh)
 	rh->cw1 = NULL;
 	crypt_storage_wrapper_destroy(rh->cw2);
 	rh->cw2 = NULL;
+	device_free(cd, rh->hotzone_device);
+	rh->hotzone_device = NULL;
 
 	free(rh->device_name);
 	free(rh->overlay_name);
@@ -2142,34 +2146,22 @@ static int reencrypt_make_targets(struct crypt_device *cd,
  * 	2) can't we derive hotzone device name from crypt context? (unlocked name, device uuid, etc?)
  */
 static int reencrypt_load_overlay_device(struct crypt_device *cd, struct luks2_hdr *hdr,
-	const char *overlay, const char *hotzone, struct volume_key *vks, uint64_t size,
+	const char *overlay, struct device *hotzone_device, struct volume_key *vks, uint64_t size,
 	uint32_t flags)
 {
-	char hz_path[PATH_MAX];
 	int r;
 
-	struct device *hz_dev = NULL;
 	struct crypt_dm_active_device dmd = {
 		.flags = flags,
 	};
 
 	log_dbg(cd, "Loading new table for overlay device %s.", overlay);
 
-	r = snprintf(hz_path, PATH_MAX, "%s/%s", dm_get_dir(), hotzone);
-	if (r < 0 || r >= PATH_MAX) {
-		r = -EINVAL;
-		goto out;
-	}
-
-	r = device_alloc(cd, &hz_dev, hz_path);
-	if (r)
-		goto out;
-
 	r = dm_targets_allocate(&dmd.segment, LUKS2_segments_count(hdr));
 	if (r)
 		goto out;
 
-	r = reencrypt_make_targets(cd, hdr, hz_dev, vks, &dmd.segment, size);
+	r = reencrypt_make_targets(cd, hdr, hotzone_device, vks, &dmd.segment, size);
 	if (r < 0)
 		goto out;
 
@@ -2178,7 +2170,6 @@ static int reencrypt_load_overlay_device(struct crypt_device *cd, struct luks2_h
 	/* what else on error here ? */
 out:
 	dm_targets_free(cd, &dmd);
-	device_free(cd, hz_dev);
 
 	return r;
 }
@@ -2305,9 +2296,13 @@ out:
 }
 
 static int reencrypt_init_device_stack(struct crypt_device *cd,
-		                     const struct luks2_reencrypt *rh)
+		                     struct luks2_reencrypt *rh)
 {
 	int r;
+	char hz_path[PATH_MAX];
+
+	assert(rh);
+	assert(!rh->hotzone_device);
 
 	/* Activate hotzone device 1:1 linear mapping to data_device */
 	r = reencrypt_activate_hotzone_device(cd, rh->hotzone_name, rh->device_size, CRYPT_ACTIVATE_PRIVATE);
@@ -2316,6 +2311,18 @@ static int reencrypt_init_device_stack(struct crypt_device *cd,
 		return r;
 	}
 
+	r = snprintf(hz_path, PATH_MAX, "%s/%s", dm_get_dir(), rh->hotzone_name);
+	if (r < 0 || r >= PATH_MAX) {
+		r = -EINVAL;
+		goto err;
+	}
+
+	r = device_alloc(cd, &rh->hotzone_device, hz_path);
+	if (r) {
+		log_err(cd, _("Failed to allocate hotzone device %s."), rh->hotzone_name);
+		goto err;
+	}
+
 	/*
 	 * Activate overlay device with exactly same table as original 'name' mapping.
 	 * Note that within this step the 'name' device may already include a table
@@ -2395,11 +2402,12 @@ static int reencrypt_refresh_overlay_devices(struct crypt_device *cd,
 		struct luks2_hdr *hdr,
 		const char *overlay,
 		const char *hotzone,
+		struct device *hotzone_device,
 		struct volume_key *vks,
 		uint64_t device_size,
 		uint32_t flags)
 {
-	int r = reencrypt_load_overlay_device(cd, hdr, overlay, hotzone, vks, device_size, flags);
+	int r = reencrypt_load_overlay_device(cd, hdr, overlay, hotzone_device, vks, device_size, flags);
 	if (r) {
 		log_err(cd, _("Failed to reload device %s."), overlay);
 		return REENC_ERR;
@@ -4083,7 +4091,8 @@ static reenc_status_t reencrypt_step(struct crypt_device *cd,
 	}
 
 	if (online) {
-		r = reencrypt_refresh_overlay_devices(cd, hdr, rh->overlay_name, rh->hotzone_name, rh->vks, rh->device_size, rh->flags);
+		r = reencrypt_refresh_overlay_devices(cd, hdr, rh->overlay_name, rh->hotzone_name,
+						      rh->hotzone_device, rh->vks, rh->device_size, rh->flags);
 		/* Teardown overlay devices with dm-error. None bio shall pass! */
 		if (r != REENC_OK)
 			return r;

lib/luks2/luks2_token.c

@@ -105,6 +105,7 @@ static void *token_dlvsym(struct crypt_device *cd,
 	log_dbg(cd, "Loading symbol %s@%s.", symbol, version);
 	sym = dlvsym(handle, symbol, version);
 #else
+	UNUSED(version);
 	log_dbg(cd, "Loading default version of symbol %s.", symbol);
 	sym = dlsym(handle, symbol);
 #endif

lib/setup.c

@@ -267,7 +267,7 @@ int init_crypto(struct crypt_device *ctx)
 		return r;
 	}
 
-	r = crypt_backend_init(crypt_fips_mode());
+	r = crypt_backend_init();
 	if (r < 0)
 		log_err(ctx, _("Cannot initialize crypto backend."));
 
@@ -3007,6 +3007,12 @@ int crypt_format_inline(struct crypt_device *cd,
 
 	log_dbg(cd, "Formatting device %s as type %s with inline tags.", mdata_device_path(cd) ?: "(none)", type);
 
+	crypt_reset_null_type(cd);
+
+	r = init_crypto(cd);
+	if (r < 0)
+		return r;
+
 	if (isINTEGRITY(type)) {
 		lparams = NULL;
 		iparams = params;
@@ -3039,7 +3045,11 @@ int crypt_format_inline(struct crypt_device *cd,
 	    iparams->journal_integrity_key_size))
 		return -EINVAL;
 
-	if (!device_is_nop_dif(idevice, &device_tag_size)) {
+	r = device_is_nop_dif(idevice, &device_tag_size);
+	if (r < 0)
+		return r;
+
+	if (!r) {
 		log_err(cd, _("Device %s does not provide inline integrity data fields."), mdata_device_path(cd));
 		return -EINVAL;
 	}
@@ -5440,6 +5450,9 @@ int crypt_activate_by_keyslot_context(struct crypt_device *cd,
 		return _activate_loopaes(cd, name, passphrase, passphrase_size, flags);
 	}
 
+	if (flags & CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF)
+		cd->memory_hard_pbkdf_lock_enabled = true;
+
 	/* acquire the volume key(s) */
 	r = -EINVAL;
 	if (isLUKS1(cd->type)) {
@@ -5911,7 +5924,7 @@ int crypt_volume_key_get_by_keyslot_context(struct crypt_device *cd,
 	struct volume_key *vk = NULL;
 
 	if (!cd || !volume_key || !volume_key_size ||
-	    (!kc && !isLUKS(cd->type) && !isTCRYPT(cd->type) && !isVERITY(cd->type)))
+	    (!kc && !isLUKS(cd->type) && !isTCRYPT(cd->type) && !isVERITY(cd->type) && !isBITLK(cd->type)))
 		return -EINVAL;
 
 	if (isLUKS2(cd->type) && keyslot != CRYPT_ANY_SLOT)
@@ -5971,6 +5984,8 @@ int crypt_volume_key_get_by_keyslot_context(struct crypt_device *cd,
 	} else if (isBITLK(cd->type)) {
 		if (kc && kc->get_bitlk_volume_key)
 			r = kc->get_bitlk_volume_key(cd, kc, &cd->u.bitlk.params, &vk);
+		else if (!kc)
+			r = BITLK_get_volume_key(cd, NULL, 0, &cd->u.bitlk.params, &vk);
 		if (r < 0)
 			log_err(cd, _("Cannot retrieve volume key for BITLK device."));
 	} else if (isFVAULT2(cd->type)) {
@@ -6780,6 +6795,16 @@ int crypt_get_verity_info(struct crypt_device *cd,
 	return 0;
 }
 
+int crypt_get_verity_repaired(struct crypt_device *cd, const char *name,
+			      uint64_t *repaired)
+
+{
+	if (!cd || !isVERITY(cd->type) || !name || !repaired)
+		return -EINVAL;
+
+	return dm_status_verity_repaired(cd, name, repaired);
+}
+
 int crypt_get_integrity_info(struct crypt_device *cd,
 	struct crypt_params_integrity *ip)
 {

lib/tcrypt/tcrypt.c

@@ -926,6 +926,26 @@ out:
 	return r;
 }
 
+static bool is_tcrypt_subdev(const char *dm_uuid, const char *base_uuid)
+{
+	const char *base_uuid_name;
+
+	assert(base_uuid);
+	base_uuid_name = strchr(base_uuid, '-');
+
+	if (!dm_uuid || !base_uuid_name)
+		return false;
+
+	if (!strncmp(dm_uuid, "SUBDEV-", 7))
+		return !strncmp(dm_uuid + 6, base_uuid_name, strlen(base_uuid_name));
+
+	/*
+	 * FIXME: Drop after shift to dependency based deactivation (CRYPT_SUBDEV)
+	 * in later releases
+	 */
+	return !strncmp(dm_uuid, base_uuid, strlen(base_uuid));
+}
+
 static int TCRYPT_remove_one(struct crypt_device *cd, const char *name,
 		      const char *base_uuid, int index, uint32_t flags)
 {
@@ -941,9 +961,7 @@ static int TCRYPT_remove_one(struct crypt_device *cd, const char *name,
 		return r;
 
 	r = dm_query_device(cd, dm_name, DM_ACTIVE_UUID, &dmd);
-	if (!r &&
+	if (!r && is_tcrypt_subdev(dmd.uuid, base_uuid))
-	    (!strncmp(dmd.uuid, base_uuid, strlen(base_uuid)) ||
-	     !dm_uuid_cmp(dmd.uuid, strchr(base_uuid, '-'))))
 		r = dm_remove_device(cd, dm_name, flags);
 
 	free(CONST_CAST(void*)dmd.uuid);
@@ -1007,7 +1025,7 @@ static int TCRYPT_status_one(struct crypt_device *cd, const char *name,
 
 	r = 0;
 
-	if (!strncmp(dmd.uuid, base_uuid, strlen(base_uuid))) {
+	if (is_tcrypt_subdev(dmd.uuid, base_uuid)) {
 		if ((c = strchr(tgt->u.crypt.cipher, '-')))
 			*c = '\0';
 		strcat(cipher, "-");

lib/utils_crypt.c

@@ -119,6 +119,21 @@ int crypt_parse_integrity_mode(const char *s, char *integrity,
 	} else if (!strcmp(s, "hmac-sha512")) {
 		strncpy(integrity, "hmac(sha512)", MAX_CIPHER_LEN);
 		ks = required_key_size ?: 64;
+	} else if (!strcmp(s, "phmac-sha1")) {
+		strncpy(integrity, "phmac(sha1)", MAX_CIPHER_LEN);
+		ks = required_key_size;
+		if (!required_key_size)
+			r = -EINVAL;
+	} else if (!strcmp(s, "phmac-sha256")) {
+		strncpy(integrity, "phmac(sha256)", MAX_CIPHER_LEN);
+		ks = required_key_size;
+		if (!required_key_size)
+			r = -EINVAL;
+	} else if (!strcmp(s, "phmac-sha512")) {
+		strncpy(integrity, "phmac(sha512)", MAX_CIPHER_LEN);
+		ks = required_key_size;
+		if (!required_key_size)
+			r = -EINVAL;
 	} else if (!strcmp(s, "cmac-aes")) {
 		strncpy(integrity, "cmac(aes)", MAX_CIPHER_LEN);
 		ks = 16;

lib/utils_device.c

@@ -1004,12 +1004,26 @@ int device_is_zoned(struct device *device)
 
 int device_is_nop_dif(struct device *device, uint32_t *tag_size)
 {
+	char *base_device_path;
+	int r;
 	struct stat st;
 
 	if (!device)
 		return -EINVAL;
 
-	if (stat(device_path(device), &st) < 0)
+	/*
+	 * For partition devices, check integrity profile on the base device.
+	 * Partition device nodes don't advertise integrity profile directly
+	 * via sysfs attributes.
+	 */
+	base_device_path = crypt_get_base_device(device_path(device));
+	if (base_device_path) {
+		r = stat(base_device_path, &st);
+		free(base_device_path);
+	} else
+		r = stat(device_path(device), &st);
+
+	if (r < 0)
 		return -EINVAL;
 
 	if (!S_ISBLK(st.st_mode))

lib/utils_dm.h

@@ -205,6 +205,7 @@ int dm_status_device(struct crypt_device *cd, const char *name);
 int dm_status_suspended(struct crypt_device *cd, const char *name);
 int dm_status_verity_ok(struct crypt_device *cd, const char *name);
 int dm_status_integrity_failures(struct crypt_device *cd, const char *name, uint64_t *count);
+int dm_status_verity_repaired(struct crypt_device *cd, const char *name, uint64_t *repaired);
 int dm_query_device(struct crypt_device *cd, const char *name,
 		    uint64_t get_flags, struct crypt_dm_active_device *dmd);
 int dm_device_deps(struct crypt_device *cd, const char *name, const char *prefix,

lib/utils_io.c

@@ -278,7 +278,7 @@ ssize_t read_lseek_blockwise(int fd, size_t bsize, size_t alignment,
 		length -= innerCount;
 	}
 
-	ret = read_blockwise(fd, bsize, alignment, buf, length);
+	ret = length ? read_blockwise(fd, bsize, alignment, buf, length) : 0;
 	if (ret >= 0)
 		ret += innerCount;
 out:

lib/utils_pbkdf.c

@@ -169,6 +169,11 @@ int verify_pbkdf_params(struct crypt_device *cd,
 		log_err(cd, _("Requested maximum PBKDF memory cannot be zero."));
 		r = -EINVAL;
 	}
+	if (pbkdf->parallel_threads > pbkdf_limits.max_parallel) {
+		log_err(cd, _("Requested maximum PBKDF parallel cost is too high (maximum is %d)."),
+			pbkdf_limits.max_parallel);
+		r = -EINVAL;
+	}
 	if (!pbkdf->parallel_threads) {
 		log_err(cd, _("Requested PBKDF parallel threads cannot be zero."));
 		r = -EINVAL;
@@ -241,12 +246,6 @@ int init_pbkdf_type(struct crypt_device *cd,
 	cd_pbkdf->max_memory_kb = pbkdf->max_memory_kb;
 	cd_pbkdf->parallel_threads = pbkdf->parallel_threads;
 
-	if (cd_pbkdf->parallel_threads > pbkdf_limits.max_parallel) {
-		log_dbg(cd, "Maximum PBKDF threads is %d (requested %d).",
-			pbkdf_limits.max_parallel, cd_pbkdf->parallel_threads);
-		cd_pbkdf->parallel_threads = pbkdf_limits.max_parallel;
-	}
-
 	/* Do not limit threads by online CPUs if user forced values (no benchmark). */
 	if (cd_pbkdf->parallel_threads && !(cd_pbkdf->flags & CRYPT_PBKDF_NO_BENCHMARK)) {
 		cpus = crypt_cpusonline();

lib/utils_storage_wrappers.c

@@ -327,24 +327,6 @@ ssize_t crypt_storage_wrapper_encrypt_write(struct crypt_storage_wrapper *cw,
 			cw->data_offset + offset);
 }
 
-ssize_t crypt_storage_wrapper_encrypt(struct crypt_storage_wrapper *cw,
-		off_t offset, void *buffer, size_t buffer_length)
-{
-	if (cw->type == NONE)
-		return 0;
-
-	if (cw->type == DMCRYPT)
-		return -ENOTSUP;
-
-	if (crypt_storage_encrypt(cw->u.cb.s,
-			cw->u.cb.iv_start + (offset >> SECTOR_SHIFT),
-			buffer_length,
-			buffer))
-		return -EINVAL;
-
-	return 0;
-}
-
 void crypt_storage_wrapper_destroy(struct crypt_storage_wrapper *cw)
 {
 	if (!cw)

lib/utils_storage_wrappers.h

@@ -53,8 +53,6 @@ ssize_t crypt_storage_wrapper_write(struct crypt_storage_wrapper *cw,
 		off_t offset, void *buffer, size_t buffer_length);
 ssize_t crypt_storage_wrapper_encrypt_write(struct crypt_storage_wrapper *cw,
 		off_t offset, void *buffer, size_t buffer_length);
-ssize_t crypt_storage_wrapper_encrypt(struct crypt_storage_wrapper *cw,
-		off_t offset, void *buffer, size_t buffer_length);
 
 int crypt_storage_wrapper_datasync(const struct crypt_storage_wrapper *cw);
 

lib/utils_wipe.c

@@ -50,7 +50,7 @@ static void wipeSpecial(char *buffer, size_t buffer_size, unsigned int turn)
 {
 	unsigned int i;
 
-	unsigned char write_modes[][3] = {
+	const unsigned char write_modes[27][4] = {
 		{"\x55\x55\x55"}, {"\xaa\xaa\xaa"}, {"\x92\x49\x24"},
 		{"\x49\x24\x92"}, {"\x24\x92\x49"}, {"\x00\x00\x00"},
 		{"\x11\x11\x11"}, {"\x22\x22\x22"}, {"\x33\x33\x33"},

man/common_footer.adoc

@@ -1,17 +1,15 @@
-
 == REPORTING BUGS
 
-Report bugs at mailto:cryptsetup@lists.linux.dev[*cryptsetup mailing list*]
+Report bugs at mailto:cryptsetup@lists.linux.dev[cryptsetup mailing list] or in https://gitlab.com/cryptsetup/cryptsetup/-/issues/new[Issues project section].
-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
 
-https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions[*Cryptsetup FAQ*]
+https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions[Cryptsetup FAQ]
 
 *cryptsetup*(8), *integritysetup*(8) and *veritysetup*(8)
 
 == CRYPTSETUP
 
-Part of https://gitlab.com/cryptsetup/cryptsetup/[*cryptsetup project*].
+Part of https://gitlab.com/cryptsetup/cryptsetup/[cryptsetup project].

man/cryptsetup-benchmark.8.adoc

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

man/cryptsetup-bitlkDump.8.adoc

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

man/cryptsetup-close.8.adoc

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

man/cryptsetup-config.8.adoc

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

man/cryptsetup-convert.8.adoc

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

man/cryptsetup-erase.8.adoc

@@ -17,16 +17,18 @@ cryptsetup-erase, cryptsetup-luksErase - erase all keyslots
 
 == DESCRIPTION
 
-Erase all keyslots and make the LUKS container permanently inaccessible.
+Erase all keyslots, removing the volume key.
-Unless the device is configured with HW OPAL support you do not need to
+Unless the device is configured with OPAL self-encrypting drive support, you do not need to provide any password for this operation.
-provide any password for this operation.
 
-*WARNING:* This operation is irreversible.
+This operation is irreversible.
+Unless you have a header backup, all old encrypted data in the container will be permanently irretrievable.
+Header backup cannot be used to recover data from OPAL self-encrypting drives, as the keys are permanently removed from hardware.
 
-*WARNING:* with *--hw-opal-factory-reset* ALL data is lost on the device,
+The *erase* does not wipe or overwrite the data area.
-regardless of the partition it is ran on, if any, and regardless of any LUKS2
+It only removes all active keyslots from the LUKS device.
-header backup, and does not require a valid LUKS2 header to be present on the
+See the cryptsetup FAQ for more information on how to wipe the whole device, including encrypted data.
-device to run.
+
+Note that the --hw-opal-factory-reset option for OPAL self-encrypting drive will erase ALL data on the drive, regardless of the partition it is run on.
 
 *<options>* can be [--header, --disable-locks, --hw-opal-factory-reset, --key-file].
 

man/cryptsetup-fvault2Dump.8.adoc

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

man/cryptsetup-isLuks.8.adoc

@@ -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].
 

man/cryptsetup-luksAddKey.8.adoc

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

man/cryptsetup-luksChangeKey.8.adoc

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

man/cryptsetup-luksConvertKey.8.adoc

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

man/cryptsetup-luksDump.8.adoc

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

man/cryptsetup-luksFormat.8.adoc

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

man/cryptsetup-luksHeaderBackup.8.adoc

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

man/cryptsetup-luksHeaderRestore.8.adoc

@@ -16,19 +16,16 @@ 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
+Restores a binary backup of the LUKS header and keyslot area from the specified file.
-specified file. +
+
-*NOTE:* Using '-' as filename reads the header backup from a file named '-'.
+Using '-' as a filename reads the header backup from a file named '-'.
+
+All 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 and backup match.
+Alternatively, the backup will also be written if the device has no LUKS header.
 
 *<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.
-
-This command requires that the volume key size and data offset of the
-LUKS header already on the device and of the header backup match.
-Alternatively, if there is no LUKS header on the device, the backup will
-also be written to it.
-
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]

man/cryptsetup-luksKillSlot.8.adoc

@@ -8,33 +8,28 @@
 
 == 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
+Wipe the keyslot with the number from the LUKS device.
-in batch-mode (-q) a remaining passphrase must be supplied, either
-interactively or via --key-file. This command can remove the last
-remaining key-slot, but requires an interactive confirmation when doing
-so. Removing the last passphrase makes a LUKS container permanently
-inaccessible.
 
-*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+Except running in batch-mode (-q), a remaining passphrase must be supplied, either interactively or via --key-file.
---header, --disable-locks, --type, --verify-passphrase, --timeout].
+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.
 
-*WARNING:* If you read the passphrase from stdin (without further
+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.
-argument or with '-' as an argument to --key-file), batch-mode (-q) will
+Removing the last passphrase makes the LUKS container permanently inaccessible.
-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
+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.
---key-file argument) and batch-mode (-q) is active, the key-slot is
+
-removed without any other warning.
+This operation removes only the key in a particular keyslot; it does not wipe any encrypted data.
+
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --verify-passphrase, --timeout].
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]

man/cryptsetup-luksRemoveKey.8.adoc

@@ -16,18 +16,15 @@ cryptsetup-luksRemoveKey - remove the supplied passphrase from the LUKS device
 
 == DESCRIPTION
 
-Removes the supplied passphrase from the LUKS device. The passphrase to
+Removes the supplied passphrase from the LUKS device.
-be removed can be specified interactively, as the positional argument or
+The passphrase to be removed can be specified interactively, as the positional argument or via --key-file.
-via --key-file.
 
-*<options>* can be [--key-file, --keyfile-offset, --keyfile-size,
+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.
---header, --disable-locks, --type, --timeout, --verify-passphrase].
+Removing the last passphrase makes the LUKS container permanently inaccessible.
 
-*WARNING:* If you read the passphrase from stdin (without further
+This operation removes only the key in a particular keyslot; it does not wipe any encrypted data.
-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
+*<options>* can be [--key-file, --keyfile-offset, --keyfile-size, --header, --disable-locks, --type, --timeout, --verify-passphrase].
-the last remaining passphrase from a LUKS container. Removing the last
-passphrase makes the LUKS container permanently inaccessible.
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]

man/cryptsetup-luksResume.8.adoc

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

man/cryptsetup-luksSuspend.8.adoc

@@ -16,22 +16,15 @@ cryptsetup-luksSuspend - suspends an active device and wipes the key
 
 == DESCRIPTION
 
-Suspends an active device (all IO operations will block and accesses to
+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.
-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,
+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.
-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
+After this operation, you must use _luksResume_ to reinstate the encryption key and unblock the device or _close_ to remove the mapped device.
-encryption key and unblock the device or _close_ to remove the mapped
+
-device.
+*WARNING:* To avoid deadlock, never suspend the device on which the cryptsetup binary resides.
 
 *<options>* can be [--header, --disable-locks].
 
-*WARNING:* Never suspend the device on which the cryptsetup binary
-resides.
-
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]

man/cryptsetup-luksUUID.8.adoc

@@ -16,8 +16,9 @@ cryptsetup-luksUUID - print or set the UUID of a LUKS device
 
 == DESCRIPTION
 
-Print the UUID of a LUKS device. +
+Print the UUID of a LUKS device.
-Set new UUID if _--uuid_ option is specified.
+
+Set new UUID if --uuid option is specified.
 
 *<options>* can be [--header, --uuid, --type, --disable-locks].
 

man/cryptsetup-open.8.adoc

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

man/cryptsetup-reencrypt.8.adoc

@@ -26,28 +26,20 @@ There are 3 basic modes of operation:
 
 <device> or --active-name <name> (LUKS2 only) is mandatory parameter.
 
-Cryptsetup _reencrypt_ action can be used to change reencryption parameters
+Cryptsetup _reencrypt_ action can be used to change reencryption parameters, which otherwise require full on-disk data change (re-encryption).
-which otherwise require full on-disk data change (re-encryption). The
+The _reencrypt_ action reencrypts data on the LUKS device in-place.
-_reencrypt_ action reencrypts data on LUKS device in-place.
 
-You can regenerate *volume key* (the real key used in on-disk encryption
+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).
-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
+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.
-from a leak) you need to use them in that order to not leak the new volume key.
 
-Reencryption process may be safely interrupted by a user via SIGINT
+The reencryption process may be safely interrupted by a user via SIGINT signal (ctrl+c).
-signal (ctrl+c). Same applies to SIGTERM signal (i.e. issued by systemd
+The same applies to the SIGTERM signal (i.e., issued by systemd during system shutdown).
-during system shutdown).
 
-For in-place encryption mode, the _reencrypt_ action additionally takes all
+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).
-options available for _luksFormat_ action for respective LUKS version (see
+See *cryptsetup-luksFormat*(8).
-cryptsetup-luksFormat man page for more details). See *cryptsetup-luksFormat*(8).
 
-*NOTE* that for encrypt and decrypt mode, the whole device must be
+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.
-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.*
 
@@ -96,60 +88,45 @@ part of the device contains plaintext.
 
 == LUKS2 REENCRYPTION
 
-With <device> parameter cryptsetup looks up active <device> dm mapping.
+With the <device> parameter, cryptsetup looks up the active <device> dm mapping.
-If no active mapping is detected, it starts offline LUKS2 reencryption
+If no active mapping is detected, it starts offline LUKS2 reencryption; otherwise, online reencryption occurs.
-otherwise online reencryption takes place.
 
-To resume already initialized or interrupted reencryption, just run the
+To resume already initialized or interrupted reencryption, just run the cryptsetup _reencrypt_ command again to continue the reencryption operation.
-cryptsetup _reencrypt_ command again to continue the reencryption
+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.
-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
+If the reencryption process was interrupted abruptly (reencryption process crash, system crash, or power off), it may require recovery.
-process crash, system crash, poweroff) it may require recovery. The
+The recovery is run automatically on next activation (action _open_) when needed or explicitly by the user (action _repair_).
-recovery is currently run automatically on next activation (action
-_open_) when needed or explicitly by user (action _repair_).
 
-Optional parameter <new_name> takes effect only with encrypt option
+The optional parameter <new_name> takes effect only with the encrypt option, and it activates device <new_name> immediately after encryption initialization is finished.
-and it activates device <new_name> immediately after encryption
+That's useful when the device needs to be ready as soon as possible and mounted (used) before full data area encryption is completed.
-initialization gets finished. That's useful when device needs to be
-ready as soon as possible and mounted (used) before full data area
-encryption is completed.
 
 == LUKS1 REENCRYPTION
 
-Current working directory must be writable and temporary files created during
+The current working directory must be writable, and temporary files created during reencryption must be present.
-reencryption must be present. During reencryption process the LUKS1 device is
+During reencryption, the LUKS1 device is marked unavailable and must be offline (no dm-crypt mapping or mounted filesystem).
-marked unavailable and must be offline (no dm-crypt mapping or mounted
-filesystem).
 
-*WARNING*: The LUKS1 reencryption code is not resistant to hardware
+*WARNING*: The LUKS1 reencryption code is not resistant to hardware or kernel failures during reencryption (you can lose your data in this case).
-or kernel failures during reencryption (you can lose your data in this case).
 
 include::man/common_options.adoc[]
 
 == EXAMPLES
 
-*NOTE*: You may drop *--type luks2* option as long as LUKS2 format is
+You may drop *--type luks2* option as long as LUKS2 format is default.
-default.
 
 === LUKS2 ENCRYPTION EXAMPLES
 
-Encrypt LUKS2 device (in-place). Make sure last 32 MiB on _/dev/plaintext_
+Encrypt LUKS2 device (in-place).
-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
+Encrypt LUKS2 device (in-place).
-_/dev/plaintext_ data is encrypted while being shifted backwards.
+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
+Make sure the last 32 MiB (tail) on the data device is unused (e.g., does not contain any data):
-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*
 
@@ -157,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*
@@ -168,9 +145,19 @@ Reencrypt LUKS2 device (refresh volume key only):
 
 *cryptsetup reencrypt /dev/encrypted_device*
 
+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 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*
 

man/cryptsetup-refresh.8.adoc

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

man/cryptsetup-repair.8.adoc

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

man/cryptsetup-resize.8.adoc

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

man/cryptsetup-ssh.8.adoc

@@ -14,12 +14,10 @@ cryptsetup-ssh - manage LUKS2 SSH token
 
 == DESCRIPTION
 
-Experimental cryptsetup plugin for unlocking LUKS2 devices with token
+Experimental cryptsetup plugin for unlocking LUKS2 devices with a token connected to an SSH server.
-connected to an SSH server.
 
-This plugin currently allows only adding a token to an existing key
+This plugin currently allows only adding a token to an existing keyslot.
-slot. See *cryptsetup(8)* for instructions on how to remove, import or
+See *cryptsetup*(8) for instructions on how to remove, import or export the token.
-export the token.
 
 === Add operation
 
@@ -27,13 +25,10 @@ export the token.
 
 Adds the SSH token to *<device>*.
 
-The specified SSH server must contain a key file on the specified path with
+The specified SSH server must contain a key file on the specified path with a passphrase for an existing keyslot on the device.
-a passphrase for an existing key slot on the device. Provided
+Provided credentials will be used by cryptsetup to get the password when opening the device using the token.
-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
+Options --ssh-server, --ssh-user, --ssh-keypath and --ssh-path are required for this operation.
-required for this operation.
 
 == OPTIONS
 
@@ -43,35 +38,34 @@ Show debug messages
 *--debug-json*::
 Show debug messages including JSON metadata
 
-*--help, -?*::
+*--help*, *-?*::
 Show help
 
-**--key-slot**=_NUM_::
+*--key-slot* _number_::
-Keyslot to assign the token to. If not specified, the token will be
+Keyslot to assign the token to.
-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_::
+*--ssh-keypath* _string_::
 Path to the SSH key for connecting to the remote server.
 
-**--ssh-path**=_STRING_::
+*--ssh-path* _string_::
 Path to the key file on the remote server.
 
-**--ssh-server**=_STRING_::
+*--ssh-server* _string_::
 IP address/URL of the remote server for this token.
 
-**--ssh-user**=_STRING_::
+*--ssh-user* _string_::
-Username used for the remote server.
+The username used for the remote server.
 
-*--verbose, -v*::
+*--verbose*, *-v*::
 Shows more detailed error messages
 
-*--version, -V*::
+*--version*, *-V*::
 Print program version
 
 == NOTES
 
-The information provided when adding the token (SSH server address, user
+The information provided when adding the token (SSH server address, user and paths) will be stored in the LUKS2 header in plaintext.
-and paths) will be stored in the LUKS2 header in plaintext.
 
 == AUTHORS
 

man/cryptsetup-tcryptDump.8.adoc

@@ -18,20 +18,16 @@ 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
+If the --dump-volume-key option is used, the TCRYPT device volume key is dumped instead of the TCRYPT header info.
-dumped instead of TCRYPT header info. Beware that the volume key (or
+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.
-concatenated volume keys if cipher chain is used) can be used to decrypt
+This means that if the volume key is compromised, the whole device has to be erased to prevent further access.
-the data stored in the TCRYPT container without a passphrase. This means
+Use this option carefully.
-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,
+The --key-file option allows a combination of file content with the passphrase
---tcrypt-system, --tcrypt-backup, --veracrypt (ignored), --disable-veracrypt,
+The --key-file option can be repeated.
---veracrypt-pim, --veracrypt-query-pim, --cipher, --hash, --header,
+Note that using keyfiles differs from LUKS keyfile logic.
---verify-passphrase, --timeout].
 
-The keyfile parameter allows a combination of file content with the
+*<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].
-passphrase and can be repeated.
 
 include::man/common_options.adoc[]
 include::man/common_footer.adoc[]

man/cryptsetup-token.8.adoc

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

man/cryptsetup.8.adoc

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

man/integritysetup.8.adoc

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

man/meson.build

@@ -23,6 +23,7 @@ cryptsetup_manpages = [
             'cryptsetup-loopaesOpen.8',
             'cryptsetup-tcryptOpen.8',
             'cryptsetup-bitlkOpen.8',
+            'cryptsetup-fvault2Open.8',
         ],
     ],
     [

man/veritysetup.8.adoc

@@ -6,7 +6,7 @@
 
 == NAME
 
-veritysetup - manage dm-verity (block level verification) volumes
+veritysetup - utility for configuring and managing dm-verity devices
 
 == SYNOPSIS
 
@@ -14,13 +14,15 @@ veritysetup - manage dm-verity (block level verification) volumes
 
 == DESCRIPTION
 
-Veritysetup is used to configure dm-verity managed device-mapper
+*Veritysetup* is a utility for configuring and managing kernel *dm-verity* devices.
-mappings.
 
-Device-mapper verity target provides read-only transparent integrity
+Kernel device-mapper *dm-verity* target provides read-only transparent data integrity protection of block devices.
-checking of block devices using kernel crypto API.
 
-The dm-verity devices are always read-only.
+When you configure the *dm-verity* device, veritysetup creates a new mapping that applications can access like any regular storage device.
+The kernel performs the verification transparently by comparing each block against pre-computed cryptographic hashes.
+The verification uses a Merkle tree and happens transparently at the kernel level without affecting applications.
+
+Verity devices can be activated during boot through *veritytab*(5), which is part of *systemd*(1).
 
 == BASIC ACTIONS
 
@@ -29,69 +31,55 @@ Veritysetup supports these operations:
 === FORMAT
 *format <data_device> <hash_device>*
 
-Calculates and permanently stores hash verification data for
+Calculates and permanently stores hash verification data for the data_device.
-data_device. Hash area can be located on the same device after data if
+Hash area can be located on the same device after data, if specified by --hash-offset option.
-specified by --hash-offset option.
 
-Note you need to provide root hash string for device verification or
+You need to provide the root hash string for device verification or activation.
-activation. Root hash must be trusted.
+Root hash must be trusted.
 
-The data or hash device argument can be block device or file image. If
+The data or hash device argument can be a block device or a file image.
-hash device path doesn't exist, it will be created as file.
+If the hash device path doesn't exist, it will be created as a file.
 
-*<options>* can be [--hash, --no-superblock, --format,
+*<options>* can be [--hash, --no-superblock, --format, --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid, --root-hash-file].
---data-block-size, --hash-block-size, --data-blocks, --hash-offset,
---salt, --uuid, --root-hash-file].
 
-If option --root-hash-file is used, the root hash is stored in
+If option --root-hash-file is used, the root hash is stored in hex-encoded text format in <path>.
-hex-encoded text format in <path>.
 
 === OPEN
 *open <data_device> <name> <hash_device> <root_hash>* +
 *open <data_device> <name> <hash_device> --root-hash-file <path>* +
-create <name> <data_device> <hash_device> <root_hash> (*OBSOLETE syntax*)
+create <name> <data_device> <hash_device> <root_hash> (OBSOLETE syntax)
 
-Creates a mapping with <name> backed by device <data_device> and using
+Creates a mapping with <name> backed by device <data_device> and using <hash_device> for in-kernel verification.
-<hash_device> for in-kernel verification.
 
 The <root_hash> is a hexadecimal string.
 
-*<options>* can be [--hash-offset, --no-superblock, --ignore-corruption
+*<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].
-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>
+If option --root-hash-file is used, the root hash is read from <path> instead of the command line parameter.
-instead of from the command line parameter. Expects hex-encoded text,
+Expects hex-encoded text, without a terminating newline.
-without terminating newline.
 
-If option --no-superblock is used, you have to use as the same options
+If --no-superblock is used, you must use the same options as in the initial format operation.
-as in initial format operation.
 
 === VERIFY
 *verify <data_device> <hash_device> <root_hash>* +
 *verify <data_device> <hash_device> --root-hash-file <path>*
 
-Verifies data on data_device with use of hash blocks stored on
+Verifies data on data_device using hash blocks stored on hash_device.
-hash_device.
 
-This command performs userspace verification, no kernel device is
+This command performs userspace verification; no kernel device is created.
-created.
 
 The <root_hash> is a hexadecimal string.
 
-If option --root-hash-file is used, the root hash is read from <path>
+If option --root-hash-file is used, the root hash is read from <path> instead of the command line parameter.
-instead of from the command line parameter. Expects hex-encoded text,
+Expects hex-encoded text, without a terminating newline.
-without terminating newline.
 
 *<options>* can be [--hash-offset, --no-superblock, --root-hash-file].
 
-If option --no-superblock is used, you have to use as the same options
+If --no-superblock is used, you must use the same options as in the initial format operation.
-as in initial format operation.
 
 === CLOSE
 *close <name>* +
-remove <name> (*OBSOLETE syntax*)
+remove <name> (OBSOLETE syntax)
 
 Removes existing mapping <name>.
 
@@ -105,216 +93,187 @@ 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].
 
 == OPTIONS
-*--batch-mode, -q*::
+*--batch-mode*, *-q*::
 Do not ask for confirmation.
 
 *--cancel-deferred*::
-Removes a previously configured deferred device removal in *close*
+Cancels a previously configured deferred device removal in the *close* command.
-command.
 
 *--check-at-most-once*::
-Instruct kernel to verify blocks only the first time they are read
+Instruct the kernel to verify blocks only once they are read from the data device, rather than every time.
-from the data device, rather than every time.
 +
-*WARNING:* It provides a reduced level of security because only offline
+*WARNING:* It provides a reduced level of security because only offline tampering of the data device's content will be detected, not online tampering.
-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*::
+*--data-blocks* _blocks_::
-Size of data device used in verification. If not specified, the whole
+Size of the data device used in verification.
-device is used.
+If not specified, the whole device is used.
 
-*--data-block-size=bytes*::
+*--data-block-size* _bytes_::
-Used block size for the data device. (Note kernel supports only
+Used block size for the data device.
-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
+Run in debug mode with full diagnostic logs.
-always prefixed by *#*.
+Debug output lines are always prefixed by *#*.
 
 *--deferred*::
-Defers device removal in *close* command until the last user closes
+Defers device removal in the *close* command until the last user closes it.
-it.
 
 *--error-as-corruption*::
-Handle device I/O errors the same as data corruption. This option must
+Handle device I/O errors the same as data corruption.
-be combined with --restart-on-corruption or --panic-on-corruption.
+This option must be combined with --restart-on-corruption or --panic-on-corruption.
 
-*--fec-device=fec_device*::
+*--fec-device* _device_::
-Use forward error correction (FEC) to recover from corruption if hash
+Use forward error correction (FEC) to recover from corruption if hash verification fails.
-verification fails. Use encoding data from the specified device.
+Use encoding data from the specified device.
 +
-The fec device argument can be block device or file image. For format,
+The FEC device argument can be a block device or a file image.
-if fec device path doesn't exist, it will be created as file.
+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
+Block sizes for data and hash devices must match.
-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
+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).
-stored on the same device with the hash tree (additional space after
+The size of this optional additional area protected by FEC is calculated from image sizes, so you must use the same images for activation.
-hash area). Size of this optional additional area protected by FEC is
-calculated from image sizes, so you must be sure that you use the same
-images for activation.
 +
-If the hash device is in a separate image, metadata covers the whole
+If the hash device is in a separate image, metadata covers the entire image after the hash area.
-rest of the image after the hash area.
 +
-If hash and FEC device is in the image, metadata ends on the FEC area
+The metadata ends on the FEC area offset if the hash and FEC device are in the image.
-offset.
 
-*--fec-offset=bytes*::
+*--fec-offset* _bytes_::
-This is the offset, in bytes, from the start of the FEC device to the
+This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data.
-beginning of the encoding data.
 
-*--fec-roots=num*::
+*--fec-roots* _number_::
-Number of generator roots. This equals to the number of parity bytes
+Number of generator roots.
-in the encoding data. In RS(M, N) encoding, the number of roots is
+This equals the number of parity bytes in the encoding data.
-M-N. M is 255 and M-N is between 2 and 24 (including).
+In RS(M, N) encoding, the number of roots is M-N.
+M is 255, and M-N is between 2 and 24 (including).
 
-*--format=number*::
+*--format* _number_::
-Specifies the hash version type. Format type 0 is original Chrome OS
+Specifies the hash version type.
-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* _hash_::
-Hash algorithm for dm-verity. For default see --help option.
+Hash algorithm for dm-verity.
+For default, see --help option.
 
-*--hash-block-size=bytes*::
+*--hash-block-size* _bytes_::
-Used block size for the hash device. (Note kernel supports only
+Used block size for the hash device.
-page-size as maximum here.)
+Maximum is the page size used by the kernel.
 
-*--hash-offset=bytes*::
+*--hash-offset* _bytes_::
-Offset of hash area/superblock on hash_device. Value must be aligned
+Offset of hash area/superblock on hash_device.
-to disk sector offset.
+Value must be aligned with the disk sector offset.
 
-*--help, -?*::
+*--help*, *-?*::
 Show help text and default parameters.
 
-*--ignore-corruption, --restart-on-corruption, --panic-on-corruption*::
+*--ignore-corruption*, *--restart-on-corruption*, *--panic-on-corruption*::
-Defines what to do if data integrity problem is detected (data
+Defines what to do if a data integrity problem (data corruption) is detected.
-corruption).
 +
-Without these options kernel fails the IO operation with I/O error. With
+Without these options, the kernel fails the I/O operation with an I/O error.
---ignore-corruption option the corruption is only logged. With
+With --ignore-corruption option, the corruption is only logged.
---restart-on-corruption or --panic-on-corruption the kernel is restarted
+With --restart-on-corruption or --panic-on-corruption, the kernel is restarted (panicked) immediately.
-(panicked) immediately. (You have to provide way how to avoid restart
+(You have to provide a way to avoid restart loops.)
-loops.)
 +
-*WARNING:* Use these options only for very specific cases. These options
+Use these options only for very specific cases.
-are available since Linux kernel version 4.1.
 
 *--ignore-zero-blocks*::
-Instruct kernel to not verify blocks that are expected to contain
+Instruct the kernel not to verify blocks expected to contain zeroes and always directly return zeroes instead.
-zeroes and always directly return zeroes instead.
 +
-*WARNING:* Use this option only in very specific cases. This option is
+Use this option only in very specific cases.
-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*::
+*--root-hash-file* _file_*::
 Path to file with stored root hash in hex-encoded text.
 
-*--root-hash-signature=FILE*::
+*--root-hash-signature* _file_*::
-Path to root hash signature file used to verify the root hash (in
+A path to the root hash signature file used to verify the root hash (in kernel).
-kernel). This feature requires Linux kernel version 5.4 or more
+This feature requires a Linux kernel version 5.4 or more recent.
-recent.
 
 *--salt=hex string*::
-Salt used for format or verification. Format is a hexadecimal string.
+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
+Allows the data device to be used in shared mode.
-for exclusive access in-before the device activation and may be mapped in multiple
+The data device is not checked for exclusive access before the device activation and may be mapped in multiple verity mappings.
-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*::
+*--uuid* _UUID_::
-Use the provided UUID for format command instead of generating new
+Use the provided UUID for the format command instead of generating a new one.
-one.
 +
-The UUID must be provided in standard UUID format, e.g.
+The UUID must be provided in standard UUID format, e.g., 12345678-1234-1234-1234-123456789abc.
-12345678-1234-1234-1234-123456789abc.
 
-*--verbose, -v*::
+*--verbose*, *-v*::
 Print more information on command execution.
 
-*--version, -V*::
+*--version*, *-V*::
 Show the program version.
 
 == RETURN CODES
 
 Veritysetup returns *0* on success and a non-zero value on error.
 
-Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
+Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory, *4* wrong device specified, *5* device already exists or device is busy.
-*4* wrong device specified, *5* device already exists or device is busy.
 
 == EXAMPLES
 
 *veritysetup --data-blocks=256 format <data_device> <hash_device>*
 
-Calculates and stores verification data on hash_device for the first 256
+Calculates and stores verification data on hash_device for the first 256 blocks (of block size).
-blocks (of block-size). If hash_device does not exist, it is created (as
+If hash_device does not exist, it is created (as a file image).
-file image).
 
 *veritysetup format --root-hash-file <path> <data_device> <hash_device>*
 
-Calculates and stores verification data on hash_device for the whole
+Calculates and stores verification data on hash_device for the whole data_device, and stores the root hash as hex-encoded text in <path>.
-data_device, and store the root hash as hex-encoded text in <path>.
 
-*veritysetup --data-blocks=256 --hash-offset=1052672 format <device>
+*veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <device>*
-<device>*
 
-Verification data (hashes) is stored on the same device as data
+Verification data (hashes) is stored on the same device as data (starting at hash-offset).
-(starting at hash-offset). Hash-offset must be greater than number of
+Hash offset must be greater than the number of blocks in the data area.
-blocks in data-area.
 
-*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device
+*veritysetup --data-blocks=256 --hash-offset=1052672 create test-device <device> <device> <root_hash>*
-<device> <device> <root_hash>*
 
-Activates the verity device named test-device. Options --data-blocks and
+Activates the verity device named test-device.
---hash-offset are the same as in the format command. The <root_hash> was
+Options --data-blocks and --hash-offset are the same as in the format command.
-calculated in format command.
+The <root_hash> was calculated in the format command.
 
-*veritysetup --data-blocks=256 --hash-offset=1052672 verify
+*veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash>*
-<data_device> <hash_device> <root_hash>*
 
 Verifies device without activation (in userspace).
 
-*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file
+*veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file <path> verify <data_device> <hash_device>*
-<path> verify <data_device> <hash_device>*
 
-Verifies device without activation (in userspace). Root hash passed via
+Verifies device without activation (in userspace).
-a file rather than inline.
+Root hash is passed via file rather than inline.
 
-*veritysetup --fec-device=<fec_device> --fec-roots=10 format
+*veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device>*
-<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
+The on-disk format specification is available on the https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[DMVerity] page.
-https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity[*DMVerity*] page.
 
 == AUTHORS
 
-The first implementation of veritysetup was written by Chrome OS
+The first implementation of veritysetup was written by Chrome OS authors.
-authors.
 
-This version is based on verification code written by
+This version is based on verification code written by mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup by mailto:gmazyland@gmail.com[Milan Broz].
-mailto:mpatocka@redhat.com[Mikulas Patocka] and rewritten for libcryptsetup
-by mailto:gmazyland@gmail.com[Milan Broz].
 
 include::man/common_footer.adoc[]

meson.build

@@ -2,7 +2,7 @@ project('cryptsetup',
     'c',
     default_options: [ 'prefix=/usr' ],
     meson_version: '>=0.64',
-    version: '2.8.0-rc0')
+    version: '2.9.0-git')
 
 libcryptsetup_version = '12.11.0'
 
@@ -31,7 +31,6 @@ default_string_options = [
     'default-luks1-cipher',
     'default-luks1-hash',
     'default-luks1-mode',
-    'default-luks2-external-tokens-path',
     'default-luks2-keyslot-cipher',
     'default-luks2-lock-path',
     'default-luks2-pbkdf',
@@ -698,6 +697,21 @@ if cc.links(
         description: 'Define to 1 to use __attribute__((symver))')
 endif
 
+# ==========================================================================
+# Check compiler support for zero_called_used_regs("used") function attribute
+if cc.links(
+        '''void _test_fn(void);
+
+        __attribute__((zero_call_used_regs("used"))) void _test_fn(void) {
+		volatile int *i; volatile int j = 0; if (j) *i = 0;
+        }
+        int main(void) { _test_fn(); return 0; }''',
+        args: ['-O0', '-Werror' ],
+        name: 'for zero_call_used_regs("used") attribute support')
+    conf.set10('HAVE_ATTRIBUTE_ZEROCALLUSEDREGS', true,
+        description: 'Define to 1 to use __attribute__((zero_call_used_regs("used")))')
+endif
+
 # ==========================================================================
 
 if get_option('dev-random')
@@ -712,7 +726,9 @@ if tmpfilesdir == ''
         method: 'pkg-config',
         required: false)
     if systemd.found()
-        tmpfilesdir = systemd.get_variable(pkgconfig: 'tmpfilesdir', default_value: '')
+        tmpfilesdir = systemd.get_variable('tmpfilesdir',
+                        pkgconfig_define: ['prefix', get_option('prefix')],
+                        default_value: '')
     endif
 endif
 
@@ -731,12 +747,12 @@ endif
 assert(get_option('default-luks2-lock-path').startswith('/'),
     'default-luks2-lock-path has to be an absolute path')
 
-luks2_external_tokens_path = get_option('default-luks2-external-tokens-path')
+luks2_external_tokens_path = get_option('luks2-external-tokens-path')
-if luks2_external_tokens_path == 'LIBDIR/cryptsetup'
+if luks2_external_tokens_path == ''
     luks2_external_tokens_path = join_paths(get_option('prefix'), get_option('libdir'), 'cryptsetup')
 endif
 assert(luks2_external_tokens_path.startswith('/'),
-    'default-luks2-external-tokens-path has to be an absolute path')
+    'luks2-external-tokens-path has to be an absolute path')
 conf.set_quoted('EXTERNAL_LUKS2_TOKENS_PATH', luks2_external_tokens_path,
     description: 'path to directory with LUKSv2 external token handlers (plugins)')
 

meson_options.txt

@@ -12,7 +12,6 @@ option('default-luks1-hash', type : 'string', description : 'hash function for L
 option('default-luks1-iter-time', type : 'integer', description : 'PBKDF2 iteration time for LUKS1 (in ms)', value : 2000)
 option('default-luks1-keybits', type : 'integer', description : 'key length in bits for LUKS1', value : 256)
 option('default-luks1-mode', type : 'string', description : 'cipher mode for LUKS1', value : 'xts-plain64')
-option('default-luks2-external-tokens-path', type : 'string', description : 'path to directory with LUKSv2 external token handlers (plugins)', value : 'LIBDIR/cryptsetup')
 option('default-luks2-iter-time', type : 'integer', description : 'Argon2 PBKDF iteration time for LUKS2 (in ms)', value : 2000)
 option('default-luks2-keyslot-cipher', type : 'string', description : 'fallback cipher for LUKS2 keyslot (if data encryption is incompatible)', value : 'aes-xts-plain64')
 option('default-luks2-keyslot-keybits', type : 'integer', description : 'fallback key size for LUKS2 keyslot (if data encryption is incompatible)', value : 512)
@@ -45,6 +44,7 @@ option('integritysetup', type : 'boolean', description : 'integritysetup Support
 option('internal-sse-argon2', type : 'boolean', description : 'use internal SSE implementation of Argon2 PBKDF', value : false)
 option('kernel_crypto', type : 'boolean', description : 'kernel userspace crypto (no benchmark and tcrypt)', value : true)
 option('keyring', type : 'boolean', description : 'kernel keyring support and builtin kernel keyring token', value : true)
+option('luks2-external-tokens-path', type : 'string', description : 'path to directory with LUKSv2 external token handlers (plugins)')
 option('luks2-reencryption', type : 'boolean', description : 'LUKS2 online reencryption extension', value : true)
 option('luks_adjust_xts_keysize', type : 'boolean', description : 'XTS mode requires two keys, double default LUKS keysize if needed', value : true)
 option('nls', type : 'boolean', description : 'use Native Language Support', value : true)

misc/fedora/cryptsetup.spec

@@ -2,7 +2,7 @@
 
 Summary: Utility for setting up encrypted disks
 Name: cryptsetup
-Version: 2.8.0-rc0
+Version: 2.8.1
 Release: 1%{?dist}
 License: GPL-2.0-or-later WITH cryptsetup-OpenSSL-exception AND LGPL-2.1-or-later WITH cryptsetup-OpenSSL-exception
 URL: https://gitlab.com/cryptsetup/cryptsetup
@@ -18,7 +18,7 @@ Obsoletes: %{name}-reencrypt <= %{version}
 Provides: %{name}-reencrypt = %{version}
 
 %global upstream_version %{version_no_tilde}
-Source0: https://www.kernel.org/pub/linux/utils/cryptsetup/v2.7/cryptsetup-%{upstream_version}.tar.xz
+Source0: https://cdn.kernel.org/pub/linux/utils/cryptsetup/v2.8/cryptsetup-%{upstream_version}.tar.xz
 
 %description
 The cryptsetup package contains a utility for setting up

po/LINGUAS

@@ -13,6 +13,7 @@ pl
 pt_BR
 ro
 ru
+sk
 sr
 sv
 uk