openharmony/third_party_fsverity-utils
1
0
Fork 0
mirror of https://github.com/openharmony/third_party_fsverity-utils.git synced 2026-07-01 10:05:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

upgrade to v1.6 ee7d74d75a727463046bf380b3de9e602a6e2b40

Browse Source 
Signed-off-by: fundavid <fangjiawei8@huawei.com>
This commit is contained in:
fundavid
2025-03-04 11:03:27 +08:00
parent 3a2d23136c
commit 786fce4e10
13 changed files with 364 additions and 290 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
+19 -19
View File
@@ -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,7 +85,7 @@ 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
@@ -96,7 +96,7 @@ jobs:
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 +107,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 +120,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 +128,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 +139,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 +150,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 +161,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
.gitignore
-1
View File
@@ -1,4 +1,3 @@
*.[1-9]
*.a
*.exe
*.o
Makefile
+5 -11
View File
@@ -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)
NEWS.md
+17
View File
@@ -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
README.OpenSource
+1 -1
View File
@@ -3,7 +3,7 @@
"Name" : "fsverity-utils",
"License" : "MIT License",
"License File" : "LICENSE",
"Version Number" : "v1.5",
"Version Number" : "v1.6",
"Owner" : "zhangdengyu2@huawei.com",
"Upstream URL" : "https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git",
"Description" : "fsverity userspace utilities"
README.md
+16 -21
View File
@@ -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;
include/libfsverity.h
+5 -5
View File
@@ -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
lib/libfsverity.pc.in
+1 -1
View File
@@ -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}
lib/sign_digest.c
+13 -11
View File
@@ -221,15 +221,6 @@ out:
return err;
}
static int
load_pkcs11_private_key(const struct libfsverity_signature_params *sig_params
__attribute__((unused)),
EVP_PKEY **pkey_ret __attribute__((unused)))
{
libfsverity_error_msg("BoringSSL doesn't support PKCS#11 tokens");
return -EINVAL;
}
#else /* OPENSSL_IS_BORINGSSL */
static BIO *new_mem_buf(const void *buf, size_t size)
@@ -333,6 +324,18 @@ out:
return err;
}
#endif /* !OPENSSL_IS_BORINGSSL */
#ifdef OPENSSL_NO_ENGINE
static int
load_pkcs11_private_key(const struct libfsverity_signature_params *sig_params
__attribute__((unused)),
EVP_PKEY **pkey_ret __attribute__((unused)))
{
libfsverity_error_msg("libfsverity was linked to a version of OpenSSL that doesn't support PKCS#11 tokens");
return -EINVAL;
}
#else
static int
load_pkcs11_private_key(const struct libfsverity_signature_params *sig_params,
EVP_PKEY **pkey_ret)
@@ -375,8 +378,7 @@ load_pkcs11_private_key(const struct libfsverity_signature_params *sig_params,
}
return 0;
}
#endif /* !OPENSSL_IS_BORINGSSL */
#endif
/* Get a private key, either from disk or from a PKCS#11 token. */
static int
man/fsverity.1
+267
View File
@@ -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 if fsverity-utils was built with a version
of OpenSSL that does not support PKCS#11 tokens.
.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).
man/fsverity.1.md
-215
View File
@@ -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).
programs/cmd_measure.c
+17 -2
View File
@@ -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))
scripts/do-release.sh
+3 -3
View File
@@ -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"