diff options
author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2024-03-26 23:03:33 +0000 |
---|---|---|
committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2024-03-26 23:03:33 +0000 |
commit | 7bbaa5db6be22394bae0de3b7acb602474e629eb (patch) | |
tree | 78b6956304e5dd081414b6919acc98c3a9fe5cc8 | |
parent | c5a0cac6b399940c07b4e00e32dddbe3895305b8 (diff) | |
parent | e5ae78dc78e1f1981b9c8158dec42a12be4af96e (diff) | |
download | fsverity-utils-sdk-release.tar.gz |
Snap for 11630439 from e5ae78dc78e1f1981b9c8158dec42a12be4af96e to sdk-releasesdk-release
Change-Id: I75734c3a4a70821a17a6adfde3ed21d1c384019a
-rw-r--r-- | .github/workflows/ci.yml | 40 | ||||
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | METADATA | 10 | ||||
-rw-r--r-- | Makefile | 16 | ||||
-rw-r--r-- | NEWS.md | 17 | ||||
-rw-r--r-- | OWNERS | 2 | ||||
-rw-r--r-- | README.md | 37 | ||||
-rw-r--r-- | include/libfsverity.h | 10 | ||||
-rw-r--r-- | lib/libfsverity.pc.in | 2 | ||||
-rw-r--r-- | man/fsverity.1 | 267 | ||||
-rw-r--r-- | man/fsverity.1.md | 215 | ||||
-rw-r--r-- | programs/cmd_measure.c | 19 | ||||
-rwxr-xr-x | scripts/do-release.sh | 6 |
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 @@ -1,4 +1,3 @@ -*.[1-9] *.a *.exe *.o @@ -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 } } @@ -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) @@ -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 @@ -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 @@ -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" |