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

rust/pvimg: Add manpages for 'pvimg' and 'genprotimg'

Browse Source 
Add manpages for 'pvimg' and 'genprotimg'.

Acked-by: Steffen Eiden <seiden@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-11-29 13:00:28 +01:00
committed by Jan Höppner
parent 72aa64495c
commit 849819cb77
5 changed files with 739 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
rust/pvimg/man/genprotimg.1 Normal file
View File

@@ -0,0 +1,265 @@
.\" Copyright 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH genprotimg 1 "2024-12-05" "s390-tools" "Genprotimg Manual"
.nh
.ad l
.SH NAME
\fBgenprotimg\fP - Create an IBM Secure Execution image
\fB
.SH SYNOPSIS
.nf
.fam C
genprotimg [OPTIONS] --kernel <FILE> --output <FILE> --host-key-document <FILE> <--no-verify|--cert <FILE>>
.fam C
.fi
.SH DESCRIPTION
.PP
Use \fBgenprotimg\fR to generate a single bootable image file with encrypted and
integrity-protected parts. The command requires a kernel image, a host-key
document, certificates for the host-key document verification, and an output
file name. Optionally, specify an initial RAM filesystem, and a file containing
the kernel parameters. If the command should be run offline, use the
\fB\-\-offline\fR option and specify the certificate revocation lists (CRLs) by
using the \fB\-\-crl\fR option. Should special circumstances require it, you can
optionally specify your own keys for the encryption by using the experimental
options. For all certificates, CRLs, and host-key documents, both the PEM and
DER input formats are supported. In the resulting image file, a plain text boot
loader, the encrypted components for kernel, initial RAM disk, kernel
parameters, and the encrypted and integrity-protected header are concatenated.
The header contains metadata necessary for running the guest in protected mode.
.PP
Use this image file as a kernel image for zipl or for a direct kernel boot using
QEMU.
.PP
.SH OPTIONS
.PP
\-i, \-\-kernel <FILE>
.RS 4
Use the content of FILE as a raw binary Linux kernel. The Linux kernel must be a
raw binary s390x Linux kernel. The ELF format is not supported.
.RE
.RE
.PP
\-r, \-\-ramdisk <FILE>
.RS 4
Use the content of FILE as the Linux initial RAM disk.
.RE
.RE
.PP
\-p, \-\-parmfile <FILE>
.RS 4
Use the content of FILE as the Linux kernel command line. The Linux kernel
command line must be shorter than the maximum kernel command line size supported
by the given Linux kernel.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Write the generated Secure Execution boot image to FILE.
.RE
.RE
.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
\-\-no\-component\-check
.RS 4
Disable all input component checks. For example, for the Linux kernel, it tests
if the given kernel looks like a raw binary s390x kernel.
.RE
.RE
.PP
\-\-overwrite
.RS 4
Overwrite an existing Secure Execution boot image.
.RE
.RE
.PP
\-\-comm\-key <FILE>
.RS 4
Use the content of FILE as the customer\-communication key (CCK). The file must
contain exactly 32 bytes of data.
.RE
.RE
.PP
\-\-enable\-dump
.RS 4
Enable Secure Execution guest dump support. This option requires the
\fB\-\-comm\-key\fR option.
.RE
.RE
.PP
\-\-disable\-dump
.RS 4
Disable Secure Execution guest dump support (default).
.RE
.RE
.PP
\-\-enable\-cck\-extension\-secret
.RS 4
Add\-secret requests must provide an extension secret that matches the
CCK\-derived extension secret. This option requires the \fB\-\-comm\-key\fR
option.
.RE
.RE
.PP
\-\-disable\-cck\-extension\-secret
.RS 4
Add\-secret requests don't have to provide the CCK\-derived extension secret
(default).
.RE
.RE
.PP
\-\-enable\-pckmo
.RS 4
Enable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
functions (default).
.RE
.RE
.PP
\-\-disable\-pckmo
.RS 4
Disable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
functions.
.RE
.RE
.PP
\-\-enable\-pckmo\-hmac
.RS 4
Enable the support for the HMAC PCKMO key encryption function.
.RE
.RE
.PP
\-\-disable\-pckmo\-hmac
.RS 4
Disable the support for the HMAC PCKMO key encryption function (default).
.RE
.RE
.PP
\-\-enable\-backup\-keys
.RS 4
Enable the support for backup target keys.
.RE
.RE
.PP
\-\-disable\-backup\-keys
.RS 4
Disable the support for backup target keys (default).
.RE
.RE
.PP
\-v, \-\-verbose
.RS 4
Provide more detailed output.
.RE
.RE
.PP
\-q, \-\-quiet
.RS 4
Provide less output.
.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
.SH EXIT STATUS
.TP 8
.B 0 - Program finished successfully
The command was executed successfully.
.RE
.TP 8
.B 1 - Generic error
Something went wrong during the operation. Refer to the error
message.
.RE
.TP 8
.B 2 - Usage error
The command was used incorrectly, for example: unsupported command
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
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,
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
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 \-\-comm\-key \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.
.IP "2." 4
An ELF file cannot be used as a Linux kernel image.
.IP "3." 4
Remember to re-run \fBzipl\fR after updating an IBM Secure Execution image.
.SH "SEE ALSO"
.sp
\fBpvimg-create\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)

246
rust/pvimg/man/pvimg-create.1 Normal file
View File

@@ -0,0 +1,246 @@
.\" Copyright 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH pvimg-create 1 "2024-12-05" "s390-tools" "Pvimg Manual"
.nh
.ad l
.SH NAME
\fBpvimg create\fP - Create an IBM Secure Execution image
\fB
.SH SYNOPSIS
.nf
.fam C
pvimg create [OPTIONS] --kernel <FILE> --output <FILE> --host-key-document <FILE> <--no-verify|--cert <FILE>>
.fam C
.fi
.SH DESCRIPTION
.PP
Use \fBpvimg\fR to generate a single bootable image file with encrypted and
integrity-protected parts. The command requires a kernel image, a host-key
document, certificates for the host-key document verification, and an output
file name. Optionally, specify an initial RAM filesystem, and a file containing
the kernel parameters. If the command should be run offline, use the
\fB\-\-offline\fR option and specify the certificate revocation lists (CRLs) by
using the \fB\-\-crl\fR option. Should special circumstances require it, you can
optionally specify your own keys for the encryption by using the experimental
options. For all certificates, CRLs, and host-key documents, both the PEM and
DER input formats are supported. In the resulting image file, a plain text boot
loader, the encrypted components for kernel, initial RAM disk, kernel
parameters, and the encrypted and integrity-protected header are concatenated.
The header contains metadata necessary for running the guest in protected mode.
.PP
Use this image file as a kernel image for zipl or for a direct kernel boot using
QEMU.
.SH OPTIONS
.PP
\-i, \-\-kernel <FILE>
.RS 4
Use the content of FILE as a raw binary Linux kernel. The Linux kernel must be a
raw binary s390x Linux kernel. The ELF format is not supported.
.RE
.RE
.PP
\-r, \-\-ramdisk <FILE>
.RS 4
Use the content of FILE as the Linux initial RAM disk.
.RE
.RE
.PP
\-p, \-\-parmfile <FILE>
.RS 4
Use the content of FILE as the Linux kernel command line. The Linux kernel
command line must be shorter than the maximum kernel command line size supported
by the given Linux kernel.
.RE
.RE
.PP
\-o, \-\-output <FILE>
.RS 4
Write the generated Secure Execution boot image to FILE.
.RE
.RE
.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
\-\-no\-component\-check
.RS 4
Disable all input component checks. For example, for the Linux kernel, it tests
if the given kernel looks like a raw binary s390x kernel.
.RE
.RE
.PP
\-\-overwrite
.RS 4
Overwrite an existing Secure Execution boot image.
.RE
.RE
.PP
\-\-comm\-key <FILE>
.RS 4
Use the content of FILE as the customer\-communication key (CCK). The file must
contain exactly 32 bytes of data.
.RE
.RE
.PP
\-\-enable\-dump
.RS 4
Enable Secure Execution guest dump support. This option requires the
\fB\-\-comm\-key\fR option.
.RE
.RE
.PP
\-\-disable\-dump
.RS 4
Disable Secure Execution guest dump support (default).
.RE
.RE
.PP
\-\-enable\-cck\-extension\-secret
.RS 4
Add\-secret requests must provide an extension secret that matches the
CCK\-derived extension secret. This option requires the \fB\-\-comm\-key\fR
option.
.RE
.RE
.PP
\-\-disable\-cck\-extension\-secret
.RS 4
Add\-secret requests don't have to provide the CCK\-derived extension secret
(default).
.RE
.RE
.PP
\-\-enable\-pckmo
.RS 4
Enable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
functions (default).
.RE
.RE
.PP
\-\-disable\-pckmo
.RS 4
Disable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
functions.
.RE
.RE
.PP
\-\-enable\-pckmo\-hmac
.RS 4
Enable the support for the HMAC PCKMO key encryption function.
.RE
.RE
.PP
\-\-disable\-pckmo\-hmac
.RS 4
Disable the support for the HMAC PCKMO key encryption function (default).
.RE
.RE
.PP
\-\-enable\-backup\-keys
.RS 4
Enable the support for backup target keys.
.RE
.RE
.PP
\-\-disable\-backup\-keys
.RS 4
Disable the support for backup target keys (default).
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help (see a summary with \fB\-h\fR).
.RE
.RE
.SH EXIT STATUS
.TP 8
.B 0 - Program finished successfully
The command was executed successfully.
.RE
.TP 8
.B 1 - Generic error
Something went wrong during the operation. Refer to the error
message.
.RE
.TP 8
.B 2 - Usage error
The command was used incorrectly, for example: unsupported command
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
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,
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
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 \-\-comm\-key \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.
.IP "2." 4
An ELF file cannot be used as a Linux kernel image.
.IP "3." 4
Remember to re-run \fBzipl\fR after updating an IBM Secure Execution image.
.SH "SEE ALSO"
.sp
\fBpvimg\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)

69
rust/pvimg/man/pvimg-info.1 Normal file
View File

@@ -0,0 +1,69 @@
.\" Copyright 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH pvimg-info 1 "2024-12-05" "s390-tools" "Pvimg Manual"
.nh
.ad l
.SH NAME
\fBpvimg info\fP - Print information about the IBM Secure Execution image
\fB
.SH SYNOPSIS
.nf
.fam C
pvimg info [OPTIONS] --format <FORMAT> <INPUT>
.fam C
.fi
.SH DESCRIPTION
Note that the API and output format is experimental and subject to change.
.SH OPTIONS
.PP
<INPUT>
.RS 4
Use INPUT as the Secure Execution image.
.RE
.RE
.PP
\-\-format <FORMAT>
.RS 4
The output format.
Possible values:
.RS 4
\- \fBjson\fP: JSON format.
.RE
.RE
.PP
\-\-key <FILE>
.RS 4
Use the key in FILE to decrypt the Secure Execution header.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help (see a summary with \fB\-h\fR).
.RE
.RE
.SH EXIT STATUS
.TP 8
.B 0 - Program finished successfully
The command was executed successfully.
.RE
.TP 8
.B 1 - Generic error
Something went wrong during the operation. Refer to the error
message.
.RE
.TP 8
.B 2 - Usage error
The command was used incorrectly, for example: unsupported command
line flag, or wrong number of arguments.
.RE
.SH "SEE ALSO"
.sp
\fBpvimg\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)

72
rust/pvimg/man/pvimg-test.1 Normal file
View File

@@ -0,0 +1,72 @@
.\" Copyright 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH pvimg-test 1 "2024-12-05" "s390-tools" "Pvimg Manual"
.nh
.ad l
.SH NAME
\fBpvimg test\fP - Test different aspects of an existing IBM Secure Execution image
\fB
.SH SYNOPSIS
.nf
.fam C
pvimg test <--host-key-document <FILE>|--key-hashes[=<FILE>]> <INPUT>
.fam C
.fi
.SH DESCRIPTION
Test different aspects of an existing IBM Secure Execution image
.SH OPTIONS
.PP
<INPUT>
.RS 4
Use INPUT as the Secure Execution image.
.RE
.RE
.PP
\-k, \-\-host\-key\-document <FILE>
.RS 4
Use FILE to check for a host key document. Verifies that the image contains the
host key hash of one of the specified host keys. The check fails if none of the
host keys match the hash in the image. This parameter can be specified multiple
times. Mutually exclusive with \fB\-\-key\-hashes\fR.
.RE
.RE
.PP
\-\-key\-hashes[=<FILE>]
.RS 4
Use FILE to check for the host key hashes provided by the ultravisor. If no FILE
is specified, FILE defaults to \fB/sys/firmware/uv/keys/all\fR. The default file
is only available if the local system supports the Query Ultravisor Keys UVC.
Verifies that the image contains the host key hash of one of the specified
hashes in FILE. The check fails if none of the host keys match a hash in the
response. Mutually exclusive with \fB\-\-host\-key\-document\fR.
.RE
.RE
.PP
\-h, \-\-help
.RS 4
Print help (see a summary with \fB\-h\fR).
.RE
.RE
.SH EXIT STATUS
.TP 8
.B 0 - Program finished successfully
The command was executed successfully.
.RE
.TP 8
.B 1 - Generic error
Something went wrong during the operation. Refer to the error
message.
.RE
.TP 8
.B 2 - Usage error
The command was used incorrectly, for example: unsupported command
line flag, or wrong number of arguments.
.RE
.SH "SEE ALSO"
.sp
\fBpvimg\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)

87
rust/pvimg/man/pvimg.1 Normal file
View File

@@ -0,0 +1,87 @@
.\" Copyright 2024 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH pvimg 1 "2024-12-05" "s390-tools" "Pvimg Manual"
.nh
.ad l
.SH NAME
\fBpvimg\fP - Create and inspect IBM Secure Execution images
\fB
.SH SYNOPSIS
.nf
.fam C
pvimg [OPTIONS] <COMMAND>
.fam C
.fi
.SH DESCRIPTION
Use pvimg to create an IBM Secure Execution image, which can be loaded using
zipl or QEMU. pvimg can also be used to inspect existing Secure Execution
images.
.SH "PVIMG COMMANDS"
.PP
\fBpvimg-create(1)\fR
.RS 4
Create an IBM Secure Execution image
.RE
.PP
\fBpvimg-info(1)\fR
.RS 4
Print information about the IBM Secure Execution image
.RE
.PP
\fBpvimg-test(1)\fR
.RS 4
Test different aspects of an existing IBM Secure Execution image
.RE
.SH OPTIONS
.PP
\-v, \-\-verbose
.RS 4
Provide more detailed output.
.RE
.RE
.PP
\-q, \-\-quiet
.RS 4
Provide less output.
.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
.SH EXIT STATUS
.TP 8
.B 0 - Program finished successfully
The command was executed successfully.
.RE
.TP 8
.B 1 - Generic error
Something went wrong during the operation. Refer to the error
message.
.RE
.TP 8
.B 2 - Usage error
The command was used incorrectly, for example: unsupported command
line flag, or wrong number of arguments.
.RE
.SH "SEE ALSO"
.sp
\fBpvimg-create\fR(1) \fBpvimg-info\fR(1) \fBpvimg-test\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)