pvimg: Add '--hdr-key' command line option to 'pvimg create'

Add '--hdr-key <FILE>' as a command line option to the 'pvimg create'
command. This key can then be used later to decrypt the Secure Execution
header of a Secure Execution image, e.g. 'pvimg info --key <FILE>
--format json <SE_IMG>'. While updating the manpages, add missing hyphen
escapes in the manpages.

Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Acked-by: Hendrik Brueckner <brueckner@linux.ibm.com>
Signed-off-by: Marc Hartmayer <mhartmay@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>

rust/pvimg/src/cli.rs

@@ -192,6 +192,9 @@ pub struct InfoArgs {
     pub format: OutputFormat,
 
     /// Use the key in FILE to decrypt the Secure Execution header.
+    ///
+    /// It is the key that was specified with the command line option
+    /// '--hdr-key' at the Secure Execution image creation.
     #[arg(long, value_name = "FILE", value_hint = ValueHint::FilePath,)]
     pub key: Option<PathBuf>,
 }
@@ -331,6 +334,14 @@ pub struct CreateBootImageArgs {
     #[arg(long, value_name = "FILE", visible_alias = "comm-key")]
     pub cck: Option<PathBuf>,
 
+    /// Use the content of FILE as the Secure Execution header protection key.
+    ///
+    /// The file must contain exactly 32 bytes of data. If the option is not
+    /// specified, the Secure Execution header protection key is a randomly
+    /// generated key.
+    #[arg(long, value_name = "FILE", alias = "x-header-key")]
+    pub hdr_key: Option<PathBuf>,
+
     #[clap(flatten)]
     pub legacy_flags: CreateBootImageLegacyFlags,
 
@@ -352,11 +363,6 @@ pub struct CreateBootImageExperimentalArgs {
     #[arg(long, value_name = "FILE", hide(true))]
     pub x_comp_key: Option<PathBuf>,
 
-    /// Manually set the Secure Execution header protection key (experimental option).
-    // Hidden in user documentation.
-    #[arg(long, value_name = "FILE", hide(true))]
-    pub x_header_key: Option<PathBuf>,
-
     /// Manually set the PSW address used for the Secure Execution header (experimental option).
     // Hidden in user documentation.
     #[arg(long, value_name = "ADDRESS", hide(true))]
@@ -494,6 +500,8 @@ mod test {
             flat_map_collect(insert(mvca.clone(), vec![CliOption::new("enable-backup-keys", ["--enable-backup-keys"])])),
             flat_map_collect(insert(mvca.clone(), vec![CliOption::new("disable-image-encryption", ["--disable-image-encryption"])])),
             flat_map_collect(insert(mvca.clone(), vec![CliOption::new("enable-image-encryption", ["--enable-image-encryption"])])),
+            flat_map_collect(insert(mvca.clone(), vec![CliOption::new("x-header-key", ["--x-header-key", "/dev/null"]),])),
+            flat_map_collect(insert(mvca.clone(), vec![CliOption::new("x-header-key", ["--hdr-key", "/dev/null"]),])),
         ];
         let invalid_create_args = [
             flat_map_collect(remove(mvcanv.clone(), "no-verify")),
@@ -521,6 +529,7 @@ mod test {
                                                    CliOption::new("disable-pckmo", ["--disable-pckmo"])])),
             flat_map_collect(insert(mvca.clone(), vec![CliOption::new("enable-image-encryption", ["--enable-image-encryption"]),
                                                    CliOption::new("disable-image-encryption", ["--disable-image-encryption"])])),
+            flat_map_collect(insert(mvca.clone(), vec![CliOption::new("x-header-key", ["--hdr-key"]),])),
         ];
 
         let mut genprotimg_valid_args = vec![

rust/pvimg/src/cmd/common.rs

@@ -25,6 +25,7 @@ pub struct UserProvidedKeys {
 /// Reads all user provided keys.
 pub fn read_user_provided_keys(
     cck_path: Option<&Path>,
+    hdr_key_path: Option<&Path>,
     experimental_args: &CreateBootImageExperimentalArgs,
 ) -> Result<UserProvidedKeys> {
     let components_key = {
@@ -43,7 +44,7 @@ pub fn read_user_provided_keys(
         }
     };
     let aead_key = {
-        match &experimental_args.x_header_key {
+        match hdr_key_path {
             Some(key_path) => {
                 info!(
                     "Use file '{}' as the Secure Execution header protection",

rust/pvimg/src/cmd/create.rs

@@ -137,7 +137,11 @@ pub fn create(opt: &CreateBootImageArgs) -> Result<OwnExitCode> {
     let verified_host_keys = opt
         .certificate_args
         .get_verified_hkds("Secure Execution image")?;
-    let user_provided_keys = read_user_provided_keys(opt.cck.as_deref(), &opt.experimental_args)?;
+    let user_provided_keys = read_user_provided_keys(
+        opt.cck.as_deref(),
+        opt.hdr_key.as_deref(),
+        &opt.experimental_args,
+    )?;
     let (plaintext_flags, secret_flags) = parse_flags(opt)?;
 
     if plaintext_flags.is_set(PcfV1::NoComponentEncryption) {