Merge remote-tracking branch 'aosp/upstream-master'HEADmastermain

Upgrade from fsverity-utils v1.5 to fsverity-utils v1.6.  There are
no significant changes, but the full changelog is shown below.

* aosp/upstream-master:
  v1.6
  Eliminate dependency on pandoc
  ci.yml: work around ASAN binaries crashing on ubuntu-latest
  ci.yml: upgrade to actions/checkout@v4 and actions/cache@v4
  cmd_measure: reject options and handle "--" correctly
  fsverity.1: update documentation for --block-size
  ci.yml: upgrade to actions/checkout@v3
  fsverity.1.md: use the new git repo URL
  README.md: use the new fsverity mailing list
  libfsverity.h: includes should be outside of extern "C" block
  ci.yml: run on push instead of pull_request
  README.md: update for latest kernel version

Update the METADATA file accordingly.  Use the new git URL.

Also delete a misleading comment from the OWNERS file.

Test: mmm external/fsverity-utils
Change-Id: Ife7ff853f516eb7a0b7cd0ccec9adfb3fa528ce2

13 files changed, 357 insertions, 285 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 309013a..f7e0a0f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,63 +6,63 @@
 # https://opensource.org/licenses/MIT.
 
 name: CI
-on: [pull_request]
+on: [push]
 
 jobs:
   static-linking-test:
     name: Test building static library
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh static_linking
 
   dynamic-linking-test:
     name: Test building dynamic library
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh dynamic_linking
 
   cplusplus-test:
     name: Test using library from C++ program
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh cplusplus
 
   uninstall-test:
     name: Test uninstalling
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh uninstall
 
   dash-test:
     name: Test building using the dash shell
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh dash
 
   license-test:
     name: Test for correct license info
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh license
 
   gcc-test:
     name: Test with gcc
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh gcc
 
   clang-test:
     name: Test with clang
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -73,7 +73,7 @@ jobs:
     name: Test building 32-bit binaries
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo dpkg --add-architecture i386
@@ -85,18 +85,20 @@ jobs:
     name: Test with sanitizers enabled
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
         sudo apt-get install -y clang llvm
+    - name: Work around https://github.com/actions/runner-images/issues/9491
+      run: sudo sysctl vm.mmap_rnd_bits=28
     - run: scripts/run-tests.sh sanitizers
 
   valgrind-test:
     name: Test with valgrind enabled
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -107,9 +109,9 @@ jobs:
     name: Test with BoringSSL
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Cache BoringSSL build
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         key: boringssl
         path: boringssl
@@ -120,7 +122,7 @@ jobs:
     name: Test with unsigned/signed char
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: scripts/run-tests.sh unsigned_char signed_char
 
   # FIXME: need a Windows build of libcrypto for this to work
@@ -128,7 +130,7 @@ jobs:
     #name: Windows build tests
     #runs-on: ubuntu-latest
     #steps:
-    #- uses: actions/checkout@v2
+    #- uses: actions/checkout@v4
     #- name: Install dependencies
       #run: |
         #sudo apt-get update
@@ -139,7 +141,7 @@ jobs:
     name: Run sparse
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -150,7 +152,7 @@ jobs:
     name: Run clang static analyzer
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -161,7 +163,7 @@ jobs:
     name: Run shellcheck
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt-get update
diff --git a/.gitignore b/.gitignore
index 3ea5ca6..35d3206 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-*.[1-9]
 *.a
 *.exe
 *.o
diff --git a/METADATA b/METADATA
index 14e8928..042baed 100644
--- a/METADATA
+++ b/METADATA
@@ -3,14 +3,14 @@ description: "This is fsverity-utils, a set of userspace utilities for fs-verity
 third_party {
   url {
     type: GIT
-    value: "https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git"
+    value: "https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git"
   }
-  version: "20e87c13075a8e5660a8d69fd6c93d4f7c5f01a5"
+  version: "2543e6e5037c0b1b448282c2793f8a6ce8b12d71"
   license_note: "would be NOTICE save for common/fsverity_uapi.h"
   license_type: RESTRICTED
   last_upgrade_date {
-    year: 2022
-    month: 2
-    day: 7
+    year: 2024
+    month: 3
+    day: 22
   }
 }
diff --git a/Makefile b/Makefile
index 2304a21..c3de571 100644
--- a/Makefile
+++ b/Makefile
@@ -70,7 +70,6 @@ QUIET_CCLD      = @echo '  CCLD    ' $@;
 QUIET_AR        = @echo '  AR      ' $@;
 QUIET_LN        = @echo '  LN      ' $@;
 QUIET_GEN       = @echo '  GEN     ' $@;
-QUIET_PANDOC    = @echo '  PANDOC  ' $@;
 endif
 USE_SHARED_LIB  ?=
 PREFIX          ?= /usr/local
@@ -205,11 +204,7 @@ EXTRA_TARGETS += $(TEST_PROGRAMS)
 
 #### Manual pages
 
-man/fsverity.1:man/fsverity.1.md
-	$(QUIET_PANDOC) pandoc $+ -s -t man > $@
-
-MAN_PAGES := man/fsverity.1
-EXTRA_TARGETS += $(MAN_PAGES)
+MAN_PAGES := $(wildcard man/*.[1-9])
 
 ##############################################################################
 
@@ -228,8 +223,7 @@ boringssl:
 
 ##############################################################################
 
-SPECIAL_TARGETS := all test_programs check install install-man uninstall \
-		   help clean
+SPECIAL_TARGETS := all test_programs check install uninstall help clean
 
 FORCE:
 
@@ -272,10 +266,10 @@ install:all
 		lib/libfsverity.pc.in \
 		> $(DESTDIR)$(LIBDIR)/pkgconfig/libfsverity.pc
 	chmod 644 $(DESTDIR)$(LIBDIR)/pkgconfig/libfsverity.pc
-
-install-man:$(MAN_PAGES)
 	install -d $(DESTDIR)$(MANDIR)/man1
-	install -m644 $+ $(DESTDIR)$(MANDIR)/man1/
+	for page in $(MAN_PAGES); do \
+		install -m644 $$page $(DESTDIR)$(MANDIR)/man1/; \
+	done
 
 uninstall:
 	rm -f $(DESTDIR)$(BINDIR)/$(FSVERITY)
diff --git a/NEWS.md b/NEWS.md
index c63dff9..d93d1c0 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,22 @@
 # fsverity-utils release notes
 
+## Version 1.6
+
+* Eliminated the dependency on `pandoc` for installing the manual page.
+
+* Updated the documentation to reflect recent kernel changes, including the
+  kernel adding support for more Merkle tree block sizes, IMA adding support for
+  fs-verity, and btrfs adding support for fs-verity.
+
+* Updated the documentation to refer to the new fsverity mailing list.
+
+* Fixed a C++ compatibility issue in `libfsverity.h`.
+
+* `fsverity measure` now follows standard command line syntax for arguments
+  beginning with hyphens.  I.e., `fsverity measure --foo` now treats `--foo` as
+  an (unsupported) option, not a filename.  To operate on a file actually named
+  `--foo`, use `fsverity measure -- --foo`.
+
 ## Version 1.5
 
 * Made the `fsverity sign` command and the `libfsverity_sign_digest()` function
diff --git a/OWNERS b/OWNERS
index 34a0faa..ff834ea 100644
--- a/OWNERS
+++ b/OWNERS
@@ -1,4 +1,2 @@
-# Default code reviewers picked from top 3 or more developers.
-# Please update this list if you find better candidates.
 ebiggers@google.com
 victorhsieh@google.com
diff --git a/README.md b/README.md
index ffa25fd..2080fb1 100644
--- a/README.md
+++ b/README.md
@@ -9,12 +9,8 @@ files, using a hidden Merkle tree (hash tree) associated with the
 file.  It is similar to dm-verity, but implemented at the file level
 rather than at the block device level.  See the [kernel
 documentation](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html)
-for more information about fs-verity.
-
-fs-verity is supported by the ext4 and f2fs filesystems in Linux v5.4
-and later when configured with `CONFIG_FS_VERITY=y` and when the
-`verity` filesystem feature flag has been enabled.  Other filesystems
-might add support for fs-verity in the future.
+for more information about fs-verity, including which filesystems
+support it.
 
 fsverity-utils currently contains just one program, `fsverity`.  The
 `fsverity` program allows you to set up fs-verity protected files.
@@ -29,7 +25,6 @@ example, on Debian-based systems, run:
 
 ```bash
     sudo apt-get install libssl-dev
-    sudo apt-get install pandoc  # optional
 ```
 
 OpenSSL must be version 1.0.0 or later.  This is the only runtime dependency.
@@ -39,16 +34,13 @@ Then, to build and install fsverity-utils:
 ```bash
     make
     sudo make install
-    sudo make install-man  # optional
 ```
 
 By default, the following targets are built and installed: the program
-`fsverity`, the static library `libfsverity.a`, and the shared library
-`libfsverity.so`.  You can also run `make check` to build and run the
-tests, or `make help` to display all available build targets.
-
-`make install-man` installs the `fsverity.1` manual page.  This step requires
-that `pandoc` be installed.
+`fsverity`, the static library `libfsverity.a`, the shared library
+`libfsverity.so`, and the manual page `fsverity.1`.  You can also run
+`make check` to build and run the tests, or `make help` to display all
+available build targets.
 
 By default, `fsverity` is statically linked to `libfsverity`.  You can
 use `make USE_SHARED_LIB=1` to use dynamic linking instead.
@@ -100,6 +92,13 @@ get any authenticity protection (as opposed to just integrity
 protection), the output of `fsverity measure` needs to be compared
 against a trusted value.
 
+### With IMA
+
+Since Linux v5.19, the kernel's IMA (Integrity Measurement
+Architecture) subsystem supports using fs-verity file digests in lieu
+of traditional file digests.  This must be configured in the IMA
+policy.  For more information, see the IMA documentation.
+
 ### Using builtin signatures
 
 First, note that fs-verity is essentially just a way of hashing a
@@ -107,7 +106,7 @@ file; it doesn't mandate a specific way of handling signatures.
 There are several possible ways that signatures could be handled:
 
 * Do it entirely in userspace
-* Use IMA appraisal (work-in-progress)
+* Use IMA appraisal
 * Use fs-verity built-in signatures
 
 Any such solution needs two parts: (a) a policy that determines which
@@ -170,23 +169,19 @@ That being said, here are some examples of using built-in signatures:
     fsverity digest file --compact --for-builtin-sig | tr -d '\n' | xxd -p -r | openssl smime -sign -in /dev/stdin ...
 ```
 
-### With IMA
-
-IMA support for fs-verity is planned.
-
 ## Notices
 
 fsverity-utils is provided under the terms of the MIT license.  A copy
 of this license can be found in the file named [LICENSE](LICENSE).
 
-Send questions and bug reports to linux-fscrypt@vger.kernel.org.
+Send questions and bug reports to fsverity@lists.linux.dev.
 
 Signed release tarballs for fsverity-utils can be found on
 [kernel.org](https://kernel.org/pub/linux/kernel/people/ebiggers/fsverity-utils/).
 
 ## Contributing
 
-Send patches to linux-fscrypt@vger.kernel.org with the additional tag
+Send patches to fsverity@lists.linux.dev with the additional tag
 `fsverity-utils` in the subject, i.e. `[fsverity-utils PATCH]`.
 Patches should follow the Linux kernel's coding style.  A
 `.clang-format` file is provided to approximate this coding style;
diff --git a/include/libfsverity.h b/include/libfsverity.h
index a0a1527..453dd95 100644
--- a/include/libfsverity.h
+++ b/include/libfsverity.h
@@ -13,16 +13,16 @@
 #ifndef LIBFSVERITY_H
 #define LIBFSVERITY_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 #include <errno.h>
 #include <stddef.h>
 #include <stdint.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #define FSVERITY_UTILS_MAJOR_VERSION	1
-#define FSVERITY_UTILS_MINOR_VERSION	5
+#define FSVERITY_UTILS_MINOR_VERSION	6
 
 #define FS_VERITY_HASH_ALG_SHA256       1
 #define FS_VERITY_HASH_ALG_SHA512       2
diff --git a/lib/libfsverity.pc.in b/lib/libfsverity.pc.in
index 4c9bb20..d537d9c 100644
--- a/lib/libfsverity.pc.in
+++ b/lib/libfsverity.pc.in
@@ -4,7 +4,7 @@ includedir=@INCDIR@
 
 Name: libfsverity
 Description: fs-verity library
-Version: 1.5
+Version: 1.6
 Libs: -L${libdir} -lfsverity
 Requires.private: libcrypto
 Cflags: -I${includedir}
diff --git a/man/fsverity.1 b/man/fsverity.1
new file mode 100644
index 0000000..0bb9f01
--- /dev/null
+++ b/man/fsverity.1
@@ -0,0 +1,267 @@
+.\" SPDX-License-Identifier: MIT
+.\"
+.\" Copyright 2021 Google LLC
+.\"
+.\" Use of this source code is governed by an MIT-style license that can be
+.\" found in the LICENSE file or at https://opensource.org/licenses/MIT.
+.\"
+.TH "FSVERITY" "1" "March 2024" "fsverity-utils v1.6" "User Commands"
+.hy
+.
+.SH NAME
+.PP
+fsverity - userspace utility for fs-verity
+.
+.
+.SH SYNOPSIS
+.PP
+\f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...]
+\f[I]FILE\f[R]\&...
+.PD 0
+.P
+.PD
+\f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...]
+\f[I]TYPE\f[R] \f[I]FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...]
+\f[I]FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&...
+.PD 0
+.P
+.PD
+\f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...]
+\f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R]
+.
+.
+.SH DESCRIPTION
+.PP
+\f[B]fsverity\f[R] is a userspace utility for fs-verity.
+fs-verity is a Linux kernel filesystem feature that does transparent on-demand
+verification of the contents of read-only files using Merkle trees.
+.PP
+\f[B]fsverity\f[R] can enable fs-verity on files, retrieve the digests of
+fs-verity files, and sign files for use with fs-verity (among other things).
+\f[B]fsverity\f[R]\[cq]s functionality is divided among various subcommands.
+.PP
+This manual page focuses on documenting all \f[B]fsverity\f[R] subcommands and
+options.
+For examples and more information about the fs-verity kernel feature, see the
+references at the end of this page.
+.
+.
+.SH OPTIONS
+.PP
+\f[B]fsverity\f[R] always accepts the following options:
+.TP
+\f[B]--help\f[R]
+Show the help, for either one subcommand or for all subcommands.
+.TP
+\f[B]--version\f[R]
+Show the version of fsverity-utils.
+.
+.
+.SH SUBCOMMANDS
+.
+.SS \f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R]\&...
+.PP
+Compute the fs-verity digest of the given file(s).
+This is mainly intended to used in preparation for signing the digest.
+In some cases \f[B]fsverity sign\f[R] can be used instead to digest and sign the
+file in one step.
+.PP
+Options accepted by \f[B]fsverity digest\f[R]:
+.TP
+\f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R]
+The Merkle tree block size (in bytes) to use.
+This must be a power of 2 and at least twice the size of the hash values.
+.RS
+.PP
+Note that the Linux kernel implementations of fs-verity place further
+restrictions on the Merkle tree block size.
+Linux v6.2 and earlier require that the Merkle tree block size be equal to both
+the system page size and the filesystem block size.
+These values are often 4096.
+Linux v6.3 and later are more flexible; they require that the Merkle tree block
+size be a power of 2 that is greater than or equal to 1024 and less than or
+equal to the system page size and the filesystem block size.
+The default value of this option is 4096.
+.RE
+.TP
+\f[B]--compact\f[R]
+When printing the file digest, only print the actual digest hex string;
+don\[cq]t print the algorithm name and filename.
+.TP
+\f[B]--for-builtin-sig\f[R]
+Format the file digest in a way that is compatible with the Linux kernel\[cq]s
+fs-verity built-in signature verification support.
+This means formatting it as a \f[B]struct fsverity_formatted_digest\f[R].
+Use this option if you are using built-in signatures but are not using
+\f[B]fsverity sign\f[R] to do the signing.
+.TP
+\f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R]
+The hash algorithm to use to build the Merkle tree.
+Valid options are sha256 and sha512.
+Default is sha256.
+.TP
+\f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R]
+Write the computed Merkle tree to the given file.
+The Merkle tree layout will be the same as that used by the Linux kernel\[cq]s
+\f[B]FS_IOC_READ_VERITY_METADATA\f[R] ioctl.
+.RS
+.PP
+Normally this option isn\[cq]t useful, but it can be needed in cases where the
+fs-verity metadata needs to be consumed by something other than one of the
+native Linux kernel implementations of fs-verity.
+This is not needed for file signing.
+.RE
+.TP
+\f[B]--out-descriptor\f[R]=\f[I]FILE\f[R]
+Write the computed fs-verity descriptor to the given file.
+.RS
+.PP
+Normally this option isn\[cq]t useful, but it can be needed in cases where the
+fs-verity metadata needs to be consumed by something other than one of the
+native Linux kernel implementations of fs-verity.
+This is not needed for file signing.
+.RE
+.TP
+\f[B]--salt\f[R]=\f[I]SALT\f[R]
+The salt to use in the Merkle tree, as a hex string.
+The salt is a value that is prepended to every hashed block; it can be used to
+personalize the hashing for a particular file or device.
+The default is no salt.
+.
+.SS \f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...] \f[I]TYPE\f[R] \f[I]FILE\f[R]
+.PP
+Dump the fs-verity metadata of the given file.
+The file must have fs-verity enabled, and the filesystem must support the
+\f[B]FS_IOC_READ_VERITY_METADATA\f[R] ioctl (it was added in Linux v5.12).
+This subcommand normally isn\[cq]t useful, but it can be useful in cases where a
+userspace server program is serving a verity file to a client which implements
+fs-verity compatible verification.
+.PP
+\f[I]TYPE\f[R] may be \[lq]merkle_tree\[rq], \[lq]descriptor\[rq], or
+\[lq]signature\[rq], indicating the type of metadata to dump.
+\[lq]signature\[rq] refers to the built-in signature, if present;
+userspace-managed signatures will not be included.
+.PP
+Options accepted by \f[B]fsverity dump_metadata\f[R]:
+.TP
+\f[B]--length\f[R]=\f[I]LENGTH\f[R]
+Length in bytes to dump from the specified metadata item.
+Only accepted in combination with \f[B]--offset\f[R].
+.TP
+\f[B]--offset\f[R]=\f[I]offset\f[R]
+Offset in bytes into the specified metadata item at which to start dumping.
+Only accepted in combination with \f[B]--length\f[R].
+.
+.SS \f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R]
+.PP
+Enable fs-verity on the specified file.
+This will only work if the filesystem supports fs-verity.
+.PP
+Options accepted by \f[B]fsverity enable\f[R]:
+.TP
+\f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--salt\f[R]=\f[I]SALT\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--signature\f[R]=\f[I]SIGFILE\f[R]
+Specifies the built-in signature to apply to the file.
+\f[I]SIGFILE\f[R] must be a file that contains the signature in PKCS#7 DER
+format, e.g.\ as produced by the \f[B]fsverity sign\f[R] command.
+.RS
+.PP
+Note that this option is only needed if the Linux kernel\[cq]s fs-verity
+built-in signature verification support is being used.
+It is not needed if the signatures will be verified in userspace, as in that
+case the signatures should be stored separately.
+.RE
+.
+.SS \f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&...
+.PP
+Display the fs-verity digest of the given file(s).
+The files must have fs-verity enabled.
+The output will be the same as \f[B]fsverity digest\f[R] with the appropriate
+parameters, but \f[B]fsverity measure\f[R] will take constant time for each file
+regardless of the size of the file.
+.PP
+\f[B]fsverity measure\f[R] does not accept any options.
+.
+.SS \f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R]
+.PP
+Sign the given file for fs-verity, in a way that is compatible with the Linux
+kernel\[cq]s fs-verity built-in signature verification support.
+The signature will be written to \f[I]OUT_SIGFILE\f[R] in PKCS#7 DER format.
+.PP
+The private key can be specified either by key file or by PKCS#11 token.
+To use a key file, provide \f[B]--key\f[R] and optionally \f[B]--cert\f[R].
+To use a PKCS#11 token, provide \f[B]--pkcs11-engine\f[R],
+\f[B]--pkcs11-module\f[R], \f[B]--cert\f[R], and optionally
+\f[B]--pkcs11-keyid\f[R].
+PKCS#11 token support is unavailable when fsverity-utils was built with
+BoringSSL rather than OpenSSL.
+.PP
+\f[B]fsverity sign\f[R] should only be used if you need compatibility with
+fs-verity built-in signatures.
+It is not the only way to do signatures with fs-verity.
+For more information, see the fsverity-utils README.
+.PP
+Options accepted by \f[B]fsverity sign\f[R]:
+.TP
+\f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--cert\f[R]=\f[I]CERTFILE\f[R]
+Specifies the file that contains the certificate, in PEM format.
+This option is required if \f[I]KEYFILE\f[R] contains only the private key and
+not also the certificate, or if a PKCS#11 token is used.
+.TP
+\f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--key\f[R]=\f[I]KEYFILE\f[R]
+Specifies the file that contains the private key, in PEM format.
+This option is required when not using a PKCS#11 token.
+.TP
+\f[B]--out-descriptor\f[R]=\f[I]FILE\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.TP
+\f[B]--pkcs11-engine\f[R]=\f[I]SOFILE\f[R]
+Specifies the path to the OpenSSL PKCS#11 engine file.
+This typically will be a path to the libp11 .so file.
+This option is required when using a PKCS#11 token.
+.TP
+\f[B]--pkcs11-keyid\f[R]=\f[I]KEYID\f[R]
+Specifies the key identifier in the form of a PKCS#11 URI.
+If not provided, the default key associated with the token is used.
+This option is only applicable when using a PKCS#11 token.
+.TP
+\f[B]--pkcs11-module\f[R]=\f[I]SOFILE\f[R]
+Specifies the path to the PKCS#11 token-specific module library.
+This option is required when using a PKCS#11 token.
+.TP
+\f[B]--salt\f[R]=\f[I]SALT\f[R]
+Same as for \f[B]fsverity digest\f[R].
+.
+.
+.SH SEE ALSO
+.PP
+For example commands and more information, see the README file for
+fsverity-utils (https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git/tree/README.md).
+.PP
+Also see the kernel documentation for
+fs-verity (https://www.kernel.org/doc/html/latest/filesystems/fsverity.html).
diff --git a/man/fsverity.1.md b/man/fsverity.1.md
deleted file mode 100644
index dd54964..0000000
--- a/man/fsverity.1.md
+++ /dev/null
@@ -1,215 +0,0 @@
-% FSVERITY(1) fsverity-utils v1.5 | User Commands
-%
-% February 2022
-
-# NAME
-
-fsverity - userspace utility for fs-verity
-
-# SYNOPSIS
-**fsverity digest** [*OPTION*...] *FILE*... \
-**fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE* \
-**fsverity enable** [*OPTION*...] *FILE* \
-**fsverity measure** *FILE*... \
-**fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*
-
-# DESCRIPTION
-
-**fsverity** is a userspace utility for fs-verity.  fs-verity is a Linux kernel
-filesystem feature that does transparent on-demand verification of the contents
-of read-only files using Merkle trees.
-
-**fsverity** can enable fs-verity on files, retrieve the digests of fs-verity
-files, and sign files for use with fs-verity (among other things).
-**fsverity**'s functionality is divided among various subcommands.
-
-This manual page focuses on documenting all **fsverity** subcommands and
-options.  For examples and more information about the fs-verity kernel feature,
-see the references at the end of this page.
-
-# OPTIONS
-
-**fsverity** always accepts the following options:
-
-**\-\-help**
-:   Show the help, for either one subcommand or for all subcommands.
-
-**\-\-version**
-:   Show the version of fsverity-utils.
-
-# SUBCOMMANDS
-
-## **fsverity digest** [*OPTION*...] *FILE*...
-
-Compute the fs-verity digest of the given file(s).  This is mainly intended to
-used in preparation for signing the digest.  In some cases **fsverity sign**
-can be used instead to digest and sign the file in one step.
-
-Options accepted by **fsverity digest**:
-
-**\-\-block-size**=*BLOCK_SIZE*
-:   The Merkle tree block size (in bytes) to use.  This must be a power of 2 and
-    at least twice the size of the hash values.  However, note that currently
-    (as of Linux kernel v5.13), the Linux kernel implementations of fs-verity
-    only support the case where the Merkle tree block size is equal to the
-    system page size, usually 4096 bytes.  The default value of this option is
-    4096.
-
-**\-\-compact**
-:   When printing the file digest, only print the actual digest hex string;
-    don't print the algorithm name and filename.
-
-**\-\-for-builtin-sig**
-:   Format the file digest in a way that is compatible with the Linux kernel's
-    fs-verity built-in signature verification support.  This means formatting it
-    as a `struct fsverity_formatted_digest`.  Use this option if you are using
-    built-in signatures but are not using **fsverity sign** to do the signing.
-
-**\-\-hash-alg**=*HASH_ALG*
-:   The hash algorithm to use to build the Merkle tree.  Valid options are
-    sha256 and sha512.  Default is sha256.
-
-**\-\-out-merkle-tree**=*FILE*
-:   Write the computed Merkle tree to the given file.  The Merkle tree layout
-    will be the same as that used by the Linux kernel's
-    `FS_IOC_READ_VERITY_METADATA` ioctl.
-
-    Normally this option isn't useful, but it can be needed in cases where the
-    fs-verity metadata needs to be consumed by something other than one of the
-    native Linux kernel implementations of fs-verity.  This is not needed for
-    file signing.
-
-**\-\-out-descriptor**=*FILE*
-:   Write the computed fs-verity descriptor to the given file.
-
-    Normally this option isn't useful, but it can be needed in cases where the
-    fs-verity metadata needs to be consumed by something other than one of the
-    native Linux kernel implementations of fs-verity.  This is not needed for
-    file signing.
-
-**\-\-salt**=*SALT*
-:   The salt to use in the Merkle tree, as a hex string.  The salt is a value
-    that is prepended to every hashed block; it can be used to personalize the
-    hashing for a particular file or device.  The default is no salt.
-
-## **fsverity dump_metadata** [*OPTION*...] *TYPE* *FILE*
-
-Dump the fs-verity metadata of the given file.  The file must have fs-verity
-enabled, and the filesystem must support the `FS_IOC_READ_VERITY_METADATA` ioctl
-(it was added in Linux v5.12).  This subcommand normally isn't useful, but it
-can be useful in cases where a userspace server program is serving a verity file
-to a client which implements fs-verity compatible verification.
-
-*TYPE* may be "merkle\_tree", "descriptor", or "signature", indicating the type
-of metadata to dump.  "signature" refers to the built-in signature, if present;
-userspace-managed signatures will not be included.
-
-Options accepted by **fsverity dump_metadata**:
-
-**\-\-length**=*LENGTH*
-:   Length in bytes to dump from the specified metadata item.  Only accepted in
-    combination with **\-\-offset**.
-
-**\-\-offset**=*offset*
-:   Offset in bytes into the specified metadata item at which to start dumping.
-    Only accepted in combination with **\-\-length**.
-
-## **fsverity enable** [*OPTION*...] *FILE*
-
-Enable fs-verity on the specified file.  This will only work if the filesystem
-supports fs-verity.
-
-Options accepted by **fsverity enable**:
-
-**\-\-block-size**=*BLOCK_SIZE*
-:   Same as for **fsverity digest**.
-
-**\-\-hash-alg**=*HASH_ALG*
-:   Same as for **fsverity digest**.
-
-**\-\-salt**=*SALT*
-:   Same as for **fsverity digest**.
-
-**\-\-signature**=*SIGFILE*
-:   Specifies the built-in signature to apply to the file.  *SIGFILE* must be a
-    file that contains the signature in PKCS#7 DER format, e.g. as produced by
-    the **fsverity sign** command.
-
-    Note that this option is only needed if the Linux kernel's fs-verity
-    built-in signature verification support is being used.  It is not needed if
-    the signatures will be verified in userspace, as in that case the signatures
-    should be stored separately.
-
-## **fsverity measure** *FILE*...
-
-Display the fs-verity digest of the given file(s).  The files must have
-fs-verity enabled.  The output will be the same as **fsverity digest** with
-the appropriate parameters, but **fsverity measure** will take constant time
-for each file regardless of the size of the file.
-
-**fsverity measure** does not accept any options.
-
-## **fsverity sign** [*OPTION*...] *FILE* *OUT_SIGFILE*
-
-Sign the given file for fs-verity, in a way that is compatible with the Linux
-kernel's fs-verity built-in signature verification support.  The signature will
-be written to *OUT_SIGFILE* in PKCS#7 DER format.
-
-The private key can be specified either by key file or by PKCS#11 token.  To use
-a key file, provide **\-\-key** and optionally **\-\-cert**.  To use a PKCS#11
-token, provide **\-\-pkcs11-engine**, **\-\-pkcs11-module**, **\-\-cert**, and
-optionally **\-\-pkcs11-keyid**.  PKCS#11 token support is unavailable when
-fsverity-utils was built with BoringSSL rather than OpenSSL.
-
-**fsverity sign** should only be used if you need compatibility with fs-verity
-built-in signatures.  It is not the only way to do signatures with fs-verity.
-For more information, see the fsverity-utils README.
-
-Options accepted by **fsverity sign**:
-
-**\-\-block-size**=*BLOCK_SIZE*
-:   Same as for **fsverity digest**.
-
-**\-\-cert**=*CERTFILE*
-:   Specifies the file that contains the certificate, in PEM format.  This
-    option is required if *KEYFILE* contains only the private key and not also
-    the certificate, or if a PKCS#11 token is used.
-
-**\-\-hash-alg**=*HASH_ALG*
-:   Same as for **fsverity digest**.
-
-**\-\-key**=*KEYFILE*
-:   Specifies the file that contains the private key, in PEM format.  This
-    option is required when not using a PKCS#11 token.
-
-**\-\-out-descriptor**=*FILE*
-:   Same as for **fsverity digest**.
-
-**\-\-out-merkle-tree**=*FILE*
-:   Same as for **fsverity digest**.
-
-**\-\-pkcs11-engine**=*SOFILE*
-:   Specifies the path to the OpenSSL PKCS#11 engine file.  This typically will
-    be a path to the libp11 .so file.  This option is required when using a
-    PKCS#11 token.
-
-**\-\-pkcs11-keyid**=*KEYID*
-:   Specifies the key identifier in the form of a PKCS#11 URI.  If not provided,
-    the default key associated with the token is used.  This option is only
-    applicable when using a PKCS#11 token.
-
-**\-\-pkcs11-module**=*SOFILE*
-:   Specifies the path to the PKCS#11 token-specific module library.  This
-    option is required when using a PKCS#11 token.
-
-**\-\-salt**=*SALT*
-:   Same as for **fsverity digest**.
-
-# SEE ALSO
-
-For example commands and more information, see the
-[README file for
-fsverity-utils](https://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/fsverity-utils.git/tree/README.md).
-
-Also see the [kernel documentation for
-fs-verity](https://www.kernel.org/doc/html/latest/filesystems/fsverity.html).
diff --git a/programs/cmd_measure.c b/programs/cmd_measure.c
index d78969c..e5cbff1 100644
--- a/programs/cmd_measure.c
+++ b/programs/cmd_measure.c
@@ -12,8 +12,13 @@
 #include "fsverity.h"
 
 #include <fcntl.h>
+#include <getopt.h>
 #include <sys/ioctl.h>
 
+static const struct option longopts[] = {
+	{NULL, 0, NULL, 0}
+};
+
 /* Display the fs-verity digest of the given verity file(s). */
 int fsverity_cmd_measure(const struct fsverity_command *cmd,
 			 int argc, char *argv[])
@@ -26,12 +31,22 @@ int fsverity_cmd_measure(const struct fsverity_command *cmd,
 	int status;
 	int i;
 
-	if (argc < 2)
+	/*
+	 * No supported options, but run getopt_long() with an empty longopts
+	 * array so that any options are rejected and "--" works as expected.
+	 */
+	if (getopt_long(argc, argv, "", longopts, NULL) != -1)
+		goto out_usage;
+
+	argv += optind;
+	argc -= optind;
+
+	if (argc < 1)
 		goto out_usage;
 
 	d = xzalloc(sizeof(*d) + FS_VERITY_MAX_DIGEST_SIZE);
 
-	for (i = 1; i < argc; i++) {
+	for (i = 0; i < argc; i++) {
 		d->digest_size = FS_VERITY_MAX_DIGEST_SIZE;
 
 		if (!open_file(&file, argv[i], O_RDONLY, 0))
diff --git a/scripts/do-release.sh b/scripts/do-release.sh
index 3f68497..9911f1a 100755
--- a/scripts/do-release.sh
+++ b/scripts/do-release.sh
@@ -52,9 +52,9 @@ prepare_release()
 		  include/libfsverity.h
 	sed -E -i "/Version:/s/[0-9]+\.[0-9]+/$VERS/" \
 		  lib/libfsverity.pc.in
-	sed -E -i -e "/^% /s/fsverity-utils v[0-9]+(\.[0-9]+)+/fsverity-utils v$VERS/" \
-		  -e "/^% /s/[a-zA-Z]+ 2[0-9]{3}/$month $year/" \
-		  man/*.[1-9].md
+	sed -E -i -e "/^\.TH /s/fsverity-utils v[0-9]+(\.[0-9]+)+/fsverity-utils v$VERS/" \
+		  -e "/^\.TH /s/[a-zA-Z]+ 2[0-9]{3}/$month $year/" \
+		  man/*.[1-9]
 	git commit -a --signoff --message="v$VERS"
 	git tag --sign "v$VERS" --message="$PKG"