kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Marc Hartmayer
2024-12-17 12:20:30 +01:00
committed by Jan Höppner
parent 352e2fe5d3
commit 3b8fdcc892
6 changed files with 51 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
rust/pvimg/man/genprotimg.1
View File

@@ -130,6 +130,14 @@ contain exactly 32 bytes of data.
.RE
.RE
.PP
\-\-hdr\-key <FILE>
.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.

18
rust/pvimg/man/pvimg-create.1
View File

@@ -129,6 +129,14 @@ contain exactly 32 bytes of data.
.RE
.RE
.PP
\-\-hdr\-key <FILE>
.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.

6
rust/pvimg/man/pvimg-info.1
View File

@@ -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 <FILE>
.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

19
rust/pvimg/src/cli.rs
View File

@@ -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![

3
rust/pvimg/src/cmd/common.rs
View File

@@ -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",

6
rust/pvimg/src/cmd/create.rs
View File

@@ -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) {