Add tool to verify host-key documents

Add a tool that can be used to verify if a given IBM host-key document is
valid. This uses the same logic (and code) as the image/request tools
for IBM Secure Execution, pvimg, pvattest, and pvsecret.

This tool basically just does the first step of the above tools; but without
creating any request or image.

Reviewed-by: Jan Höppner <hoeppner@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/Cargo.lock

@@ -679,6 +679,18 @@ dependencies = [
  "utils",
 ]
 
+[[package]]
+name = "pvverify"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "clap",
+ "clap_complete",
+ "log",
+ "s390_pv",
+ "utils",
+]
+
 [[package]]
 name = "quick-error"
 version = "1.2.3"

rust/Cargo.toml

@@ -8,6 +8,7 @@ members = [
 	"pvimg",
 	"pvinfo",
 	"pvsecret",
+	"pvverify",
 	"utils",
 ]
 resolver = "2"

rust/Makefile

@@ -25,7 +25,7 @@ endif #HOSTARCH
 
 ifneq (${HAVE_OPENSSL},0)
 ifneq (${HAVE_LIBCURL},0)
-	PV_TARGETS := pvsecret pvattest pvimg
+	PV_TARGETS := pvsecret pvattest pvimg pvverify
 
 ifeq ($(HOST_ARCH),s390x)
 	PV_TARGETS += pvapconfig pvinfo

rust/pvverify/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "pvverify"
+version = "0.12.0"
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = { version = "1.0.95", features = ["std"] }
+clap = { version ="4.5", features = ["derive", "wrap_help"]}
+log = { version = "0.4.25", features = ["std", "release_max_level_debug"] }
+
+pv = { path = "../pv" , package = "s390_pv" }
+utils = { path = "../utils"}
+
+[lints]
+workspace = true
+
+[build-dependencies]
+clap = { version ="4.5", features = ["derive", "wrap_help"]}
+clap_complete = "4.5"
+
+utils = { path = "../utils" }

rust/pvverify/README.md

@@ -0,0 +1,65 @@
+<!--Copyright IBM Corp. 2025 -->
+# pvverify
+## Synopsis
+`pvverify [OPTIONS] --host-key-document <FILE> <--no-verify|--cert <FILE>>`
+## Description
+Tool to verify host-keys Tool to verify host-keys. Use this tool to verify the
+chain of trust for IBM Secure
+## Options
+
+`-k`, `--host-key-document <FILE>`
+<ul>
+Use FILE as a host-key document. Can be specified multiple times and must be
+specified at least once.
+</ul>
+
+
+`--no-verify`
+<ul>
+Disable the host-key document verification. Does not require the host-key
+documents to be valid. Do not use for a production request unless you verified
+the host-key document beforehand.
+</ul>
+
+
+`-C`, `--cert <FILE>`
+<ul>
+Use FILE as a certificate to verify the host-key or keys. The certificates are
+used to establish a chain of trust for the verification of the host-key
+documents. Specify this option twice to specify the IBM Z signing key and the
+intermediate CA certificate (signed by the root CA).
+</ul>
+
+
+`--crl <FILE>`
+<ul>
+Use FILE as a certificate revocation list (CRL). The list is used to check
+whether a certificate of the chain of trust is revoked. Specify this option
+multiple times to use multiple CRLs.
+</ul>
+
+
+`--offline`
+<ul>
+Make no attempt to download CRLs.
+</ul>
+
+
+`--root-ca <ROOT_CA>`
+<ul>
+Use FILE as the root-CA certificate for the verification. If omitted, the system
+wide-root CAs installed on the system are used. Use this only if you trust the
+specified certificate.
+</ul>
+
+
+`--version`
+<ul>
+Print version information and exit.
+</ul>
+
+
+`-h`, `--help`
+<ul>
+Print help (see a summary with '-h').
+</ul>

rust/pvverify/build.rs

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+//
+// Copyright IBM Corp. 2025
+
+#![allow(missing_docs)]
+use clap::{CommandFactory, ValueEnum};
+use clap_complete::{generate_to, Shell};
+use std::env;
+use std::io::Error;
+
+include!("src/cli.rs");
+
+fn main() -> Result<(), Error> {
+    let outdir = env::var_os("OUT_DIR").unwrap();
+    let crate_name = env!("CARGO_PKG_NAME");
+    let mut cmd = CliOptions::command();
+    for &shell in Shell::value_variants() {
+        generate_to(shell, &mut cmd, crate_name, &outdir)?;
+    }
+
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=src/cli.rs");
+    println!("cargo:rerun-if-changed=../utils/src/cli.rs");
+    Ok(())
+}

rust/pvverify/man/pvverify.1

@@ -0,0 +1,76 @@
+.\" Copyright IBM Corp. 2025
+
+.TH "PVVERIFY" "1" "2025-12-09" "s390-tools" "Pvverify Manual"
+.nh
+.ad l
+.SH NAME
+pvverify \- Tool to verify host-keys
+.SH SYNOPSIS
+.nf
+.fam C
+pvverify [OPTIONS] --host-key-document <FILE> <--no-verify|--cert <FILE>>
+.fam C
+.fi
+.SH DESCRIPTION
+Tool to verify host\-keys. Use this tool to verify the chain of trust for IBM
+Secure
+.SH OPTIONS
+
+.PP
+\-k, \-\-host\-key\-document <FILE>
+.RS 4
+Use FILE as a host\-key document. Can be specified multiple times and must be
+specified at least once.
+.RE
+.RE
+.PP
+\-\-no\-verify
+.RS 4
+Disable the host\-key document verification. Does not require the host\-key
+documents to be valid. Do not use for a production request unless you verified
+the host\-key document beforehand.
+.RE
+.RE
+.PP
+\-C, \-\-cert <FILE>
+.RS 4
+Use FILE as a certificate to verify the host\-key or keys. The certificates are
+used to establish a chain of trust for the verification of the host\-key
+documents. Specify this option twice to specify the IBM Z signing key and the
+intermediate CA certificate (signed by the root CA).
+.RE
+.RE
+.PP
+\-\-crl <FILE>
+.RS 4
+Use FILE as a certificate revocation list (CRL). The list is used to check
+whether a certificate of the chain of trust is revoked. Specify this option
+multiple times to use multiple CRLs.
+.RE
+.RE
+.PP
+\-\-offline
+.RS 4
+Make no attempt to download CRLs.
+.RE
+.RE
+.PP
+\-\-root\-ca <ROOT_CA>
+.RS 4
+Use FILE as the root\-CA certificate for the verification. If omitted, the
+system wide\-root CAs installed on the system are used. Use this only if you
+trust the specified certificate.
+.RE
+.RE
+.PP
+\-\-version
+.RS 4
+Print version information and exit.
+.RE
+.RE
+.PP
+\-h, \-\-help
+.RS 4
+Print help (see a summary with \fB\-h\fR).
+.RE
+.RE

rust/pvverify/src/cli.rs

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+//
+// Copyright IBM Corp. 2025
+use std::sync::OnceLock;
+
+use clap::{ArgAction, Parser};
+use utils::CertificateOptions;
+
+static VERSION: OnceLock<String> = OnceLock::new();
+
+#[derive(Parser, Debug)]
+#[command(long_version=ver(), disable_version_flag(true))]
+/// Tool to verify host-keys
+///
+/// Tool to verify host-keys. Use this tool to verify the chain of trust for IBM Secure
+pub struct CliOptions {
+    #[command(flatten)]
+    pub certificate_args: CertificateOptions,
+
+    #[arg(long, action=ArgAction::Version)]
+    /// Print version information and exit.
+    version: (),
+}
+
+fn ver() -> &'static str {
+    VERSION.get_or_init(|| utils::tools_version_fmt!(2025))
+}

rust/pvverify/src/main.rs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+//
+// Copyright IBM Corp. 2025
+#![allow(missing_docs)]
+
+mod cli;
+
+use anyhow::Result;
+use clap::Parser;
+use log::{info, LevelFilter};
+use utils::PvLogger;
+
+static LOGGER: PvLogger = PvLogger;
+
+fn main() -> Result<()> {
+    LOGGER.start(LevelFilter::Trace)?;
+    cli::CliOptions::parse()
+        .certificate_args
+        .get_verified_hkds("info")?;
+    info!("Host-key documents verified.");
+    Ok(())
+}