diff --git a/rust/pvimg/man/genprotimg.1 b/rust/pvimg/man/genprotimg.1 index feba3916..bc3375ee 100644 --- a/rust/pvimg/man/genprotimg.1 +++ b/rust/pvimg/man/genprotimg.1 @@ -130,6 +130,14 @@ contain exactly 32 bytes of data. .RE .RE .PP +\-\-hdr\-key +.RS 4 +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. +.RE +.RE +.PP \-\-enable\-dump .RS 4 Enable Secure Execution guest dump support. This option requires the @@ -252,22 +260,22 @@ line flag, or wrong number of arguments. .RE .SH EXAMPLES These are examples of how to generate an IBM Secure Execution image in -\fI\,/boot/secure-linux\/\fR, using the kernel file \fI\,/boot/vmlinuz\/\fR, the +\fI\,/boot/secure\-linux\/\fR, using the kernel file \fI\,/boot/vmlinuz\/\fR, the initrd in \fI\,/boot/initrd.img\/\fR, the kernel parameters contained in \fI\,parmfile\/\fR, the intermediate CA in \fI\,DigiCertCA.crt\/\fR, the IBM Z -signing key in \fI\,ibm-z-host-key-signing.crt\/\fR, and the host-key document -in \fI\,host_key.crt\/\fR. An AES-256 GCM key is stored in \fI\,comm-key\/\fR, +signing key in \fI\,ibm\-z\-host\-key\-signing.crt\/\fR, and the host-key document +in \fI\,host_key.crt\/\fR. An AES-256 GCM key is stored in \fI\,comm\-key\/\fR, which is used when creating a Secure Execution image with guest dump support enabled in the second example. Generate an IBM Secure Execution image: .PP -.B genprotimg \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure-linux\/\fR +.B genprotimg \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm\-z\-host\-key\-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure\-linux\/\fR Generate an IBM Secure Execution image with Secure Execution guest dump support: .PP -.B genprotimg \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure-linux\/\fR \-\-enable\-dump \-\-cck \fI\,comm-key\fR +.B genprotimg \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm\-z\-host\-key\-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure\-linux\/\fR \-\-enable\-dump \-\-cck \fI\,comm-key\fR .SH NOTES .IP "1." 4 The \fBgenprotimg\fR(1) command is a symbolic link to the \fBpvimg-create\fR(1) command. diff --git a/rust/pvimg/man/pvimg-create.1 b/rust/pvimg/man/pvimg-create.1 index d6b4c3ac..1a12e6e8 100644 --- a/rust/pvimg/man/pvimg-create.1 +++ b/rust/pvimg/man/pvimg-create.1 @@ -129,6 +129,14 @@ contain exactly 32 bytes of data. .RE .RE .PP +\-\-hdr\-key +.RS 4 +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. +.RE +.RE +.PP \-\-enable\-dump .RS 4 Enable Secure Execution guest dump support. This option requires the @@ -233,22 +241,22 @@ line flag, or wrong number of arguments. .RE .SH EXAMPLES These are examples of how to generate an IBM Secure Execution image in -\fI\,/boot/secure-linux\/\fR, using the kernel file \fI\,/boot/vmlinuz\/\fR, the +\fI\,/boot/secure\-linux\/\fR, using the kernel file \fI\,/boot/vmlinuz\/\fR, the initrd in \fI\,/boot/initrd.img\/\fR, the kernel parameters contained in \fI\,parmfile\/\fR, the intermediate CA in \fI\,DigiCertCA.crt\/\fR, the IBM Z -signing key in \fI\,ibm-z-host-key-signing.crt\/\fR, and the host-key document -in \fI\,host_key.crt\/\fR. An AES-256 GCM key is stored in \fI\,comm-key\/\fR, +signing key in \fI\,ibm\-z\-host\-key\-signing.crt\/\fR, and the host-key document +in \fI\,host_key.crt\/\fR. An AES-256 GCM key is stored in \fI\,comm\-key\/\fR, which is used when creating a Secure Execution image with guest dump support enabled in the second example. Generate an IBM Secure Execution image: .PP -.B pvimg create \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure-linux\/\fR +.B pvimg create \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm\-z\-host\-key\-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure\-linux\/\fR Generate an IBM Secure Execution image with Secure Execution guest dump support: .PP -.B pvimg create \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure-linux\/\fR \-\-enable\-dump \-\-cck \fI\,comm-key\fR +.B pvimg create \-i \fI\,/boot/vmlinuz\/\fR \-r \fI\,/boot/initrd.img\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm\-z\-host\-key\-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/secure\-linux\/\fR \-\-enable\-dump \-\-cck \fI\,comm\-key\fR .SH NOTES .IP "1." 4 The \fBgenprotimg\fR(1) command is a symbolic link to the \fBpvimg-create\fR(1) command. diff --git a/rust/pvimg/man/pvimg-info.1 b/rust/pvimg/man/pvimg-info.1 index d2726c35..82b42da2 100644 --- a/rust/pvimg/man/pvimg-info.1 +++ b/rust/pvimg/man/pvimg-info.1 @@ -3,7 +3,7 @@ .\" it under the terms of the MIT license. See LICENSE for details. .\" -.TH pvimg-info 1 "2024-12-11" "s390-tools" "Pvimg Manual" +.TH pvimg-info 1 "2024-12-17" "s390-tools" "Pvimg Manual" .nh .ad l .SH NAME @@ -39,7 +39,9 @@ Possible values: .PP \-\-key .RS 4 -Use the key in FILE to decrypt the Secure Execution header. +Use the key in FILE to decrypt the Secure Execution header. It is the key that +was specified with the command line option \fB\-\-hdr\-key\fR at the Secure +Execution image creation. .RE .RE .PP diff --git a/rust/pvimg/src/cli.rs b/rust/pvimg/src/cli.rs index e622e1de..9deb87aa 100644 --- a/rust/pvimg/src/cli.rs +++ b/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, } @@ -331,6 +334,14 @@ pub struct CreateBootImageArgs { #[arg(long, value_name = "FILE", visible_alias = "comm-key")] pub cck: Option, + /// 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, + #[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, - /// 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, - /// 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![ diff --git a/rust/pvimg/src/cmd/common.rs b/rust/pvimg/src/cmd/common.rs index 6b46ced3..8da99d63 100644 --- a/rust/pvimg/src/cmd/common.rs +++ b/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 { 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", diff --git a/rust/pvimg/src/cmd/create.rs b/rust/pvimg/src/cmd/create.rs index cc754a14..3e2ca655 100644 --- a/rust/pvimg/src/cmd/create.rs +++ b/rust/pvimg/src/cmd/create.rs @@ -137,7 +137,11 @@ pub fn create(opt: &CreateBootImageArgs) -> Result { 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) {