rust: Refactoring and reduce API surface

Prepare pv & pv_core crates to be released on crates.io:
* Remove any unused API to stay flexible
* Remove utils dependency
* Move cli, tmpfile and version utilities to local utils crate
* Use the new utilities in the pv tools
* Rename Secret into Confidential to avoid confusion of Secret (now
  Confidential) and AddSecret requests.
* Move the uvsecret module out of the request module and change the name
  to secret.
* Cleanup dependencies
* Precise and correct minimal dependency versions
* Inline `Aes256Key::from_digest`

The cleanup ensures that the code also compiles with the dependencies
resolved to their minimal versions using:

$ cargo +nightly -Z minimal-versions update
$ cargo build

For more information refer to this blog post:
https://users.rust-lang.org/t/psa-please-specify-precise-dependency-versions-in-cargo-toml/71277/8

Signed-off-by: Marc Hartmayer <mhartmay@de.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/utils/src/cli.rs

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: MIT
+//
+// Copyright IBM Corp. 2023, 2024
+
+use clap::{ArgGroup, Args, Command, ValueHint};
+use log::{info, warn};
+use pv::misc::read_file;
+use pv::{
+    misc::{create_file, open_file, read_certs},
+    request::{
+        openssl::pkey::{PKey, Public},
+        HkdVerifier,
+    },
+    Error, Result,
+};
+use std::io::{Read, Write};
+use std::path::Path;
+use std::process::ExitCode;
+
+/// CLI Argument collection for handling certificates.
+#[derive(Args, Debug, PartialEq, Eq, Default)]
+#[command(
+    group(ArgGroup::new("pv_verify").required(true).args(["no_verify", "certs"])),
+    )]
+pub struct CertificateOptions {
+    /// Use FILE as a host-key document.
+    ///
+    /// Can be specified multiple times and must be used at least once.
+    #[arg(
+        short = 'k',
+        long = "host-key-document",
+        value_name = "FILE",
+        required = true,
+        value_hint = ValueHint::FilePath,
+        use_value_delimiter = true,
+        value_delimiter = ',',
+        )]
+    pub host_key_documents: Vec<String>,
+
+    /// 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.
+    #[arg(long)]
+    pub no_verify: bool,
+
+    /// 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).
+    #[arg(
+        short= 'C',
+        long = "cert",
+        value_name = "FILE",
+        alias("crt"),
+        value_hint = ValueHint::FilePath,
+        use_value_delimiter = true,
+        value_delimiter = ',',
+    )]
+    pub certs: Vec<String>,
+
+    /// Use FILE as a certificate revocation list.
+    ///
+    /// 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.
+    #[arg(
+        long = "crl",
+        requires("certs"),
+        value_name = "FILE",
+        value_hint = ValueHint::FilePath,
+        use_value_delimiter = true,
+        value_delimiter = ',',
+    )]
+    pub crls: Vec<String>,
+
+    /// Make no attempt to download CRLs.
+    #[arg(long, requires("certs"))]
+    pub offline: bool,
+
+    /// 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.
+    #[arg(long, requires("certs"))]
+    pub root_ca: Option<String>,
+}
+
+impl CertificateOptions {
+    /// Returns the verifier of this [`CertificateOptions`] based on the given CLI options.
+    ///
+    /// - `protectee`: what you want to create. e.g. add-secret request or SE-image
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if [`crate::request::HkdVerifier`] cannot be created.
+    fn verifier(&self, protectee: &'static str) -> Result<Box<dyn HkdVerifier>> {
+        use pv::request::{CertVerifier, NoVerifyHkd};
+        match self.no_verify {
+            true => {
+                log::warn!(
+                    "Host-key document verification is disabled. The {protectee} may not be protected."
+                );
+                Ok(Box::new(NoVerifyHkd))
+            }
+            false => Ok(Box::new(CertVerifier::new(
+                &self.certs.iter().map(Path::new).collect::<Vec<_>>(),
+                &self.crls.iter().map(Path::new).collect::<Vec<_>>(),
+                self.root_ca.as_ref().map(Path::new),
+                self.offline,
+            )?)),
+        }
+    }
+
+    /// Read the host-keys specified and verifies them if required
+    ///
+    /// - `protectee`: what you want to create. e.g. add-secret request or SE-image
+    ///
+    /// # Error
+    /// Returns an error if something went wrong during parsing the HKDs, the verification chain
+    /// could not built, or when the verification
+    /// failed.
+    pub fn get_verified_hkds(&self, protectee: &'static str) -> Result<Vec<PKey<Public>>> {
+        let hkds = &self.host_key_documents;
+        let verifier = self.verifier(protectee)?;
+
+        let mut res = Vec::with_capacity(hkds.len());
+        for hkd in hkds {
+            let hk = read_file(hkd, "host-key document")?;
+            let certs = read_certs(&hk).map_err(|source| Error::HkdNotPemOrDer {
+                hkd: hkd.to_string(),
+                source,
+            })?;
+            if certs.is_empty() {
+                return Err(Error::NoHkdInFile(hkd.to_string()));
+            }
+            if certs.len() != 1 {
+                warn!("The host-key document in '{hkd}' contains more than one certificate!")
+            }
+
+            // Panic: len is == 1 -> unwrap will succeed/not panic
+            let c = certs.first().unwrap();
+            verifier.verify(c)?;
+            res.push(c.public_key()?);
+            info!("Use host-key document at '{hkd}'");
+        }
+        Ok(res)
+    }
+}
+
+/// stdout
+pub const STDOUT: &str = "-";
+/// stdin
+pub const STDIN: &str = "-";
+
+/// Converts an argument value into a Writer.
+pub fn get_writer_from_cli_file_arg(path: &str) -> Result<Box<dyn Write>> {
+    if path == STDOUT {
+        Ok(Box::new(std::io::stdout()))
+    } else {
+        Ok(Box::new(create_file(path)?))
+    }
+}
+
+/// Converts an argument value into a Reader.
+pub fn get_reader_from_cli_file_arg(path: &str) -> Result<Box<dyn Read>> {
+    if path == STDIN {
+        Ok(Box::new(std::io::stdin()))
+    } else {
+        Ok(Box::new(open_file(path)?))
+    }
+}
+
+/// Print an error that occured during CLI parsing
+pub fn print_cli_error(e: clap::Error, mut cmd: Command) -> ExitCode {
+    let ret = if e.use_stderr() {
+        ExitCode::FAILURE
+    } else {
+        ExitCode::SUCCESS
+    };
+    // Ignore any errors during printing of the error
+    let _ = e.format(&mut cmd).print();
+    ret
+}
+
+/// Print an error to stderr
+pub fn print_error<E>(e: &E, verbosity: u8) -> ExitCode
+where
+    // Error trait is not required, but here to limit the usage to errors
+    E: AsRef<dyn std::error::Error> + std::fmt::Debug + std::fmt::Display,
+{
+    if verbosity > 0 {
+        // Debug formatter also prints the whole error stack
+        // So only print it when on verbose
+        eprintln!("error: {e:?}")
+    } else {
+        eprintln!("error: {e}")
+    };
+    ExitCode::FAILURE
+}
+
+#[cfg(test)]
+mod test {
+    use clap::Parser;
+
+    use super::*;
+
+    #[test]
+    #[rustfmt::skip]
+    fn cli_args() {
+        //Verify only that some arguments are optional, we do not want to test clap, only the
+        //configuration
+        let valid_args = [vec!["pgr", "-k", "hkd.crt", "--no-verify"], vec!["pgr", "-k", "hkd.crt", "--crt", "abc.crt"]];
+        // Test for the minimal amount of flags to yield an invalid combination
+        let invalid_args = [
+            vec!["pgr", "-k", "hkd.crt"],
+            vec!["pgr", "--no-verify", "--crt", "abc.crt"],
+            vec!["pgr", "--no-verify", "--crt", "abc.crt", "--offline"],
+            vec!["pgr", "--no-verify", "--crt", "abc.crt", "--crl", "abc.crl"],
+            vec!["pgr", "--no-verify", "--crt", "abc.crt", "--root-ca", "root.crt"],
+            vec!["pgr", "--offline"],
+            vec!["pgr", "--crl", "abc.crl"],
+            vec!["pgr", "--root-ca", "root.crt"],
+        ];
+        #[derive(Parser, Debug)]
+        struct TestParser {
+            #[command(flatten)]
+            pub verify_args: CertificateOptions,
+        }
+
+        for arg in valid_args {
+            let res = TestParser::try_parse_from(&arg);
+            assert!(res.is_ok());
+        }
+
+        for arg in invalid_args {
+            let res = TestParser::try_parse_from(&arg);
+            assert!(res.is_err());
+        }
+    }
+}