diff --git a/rust/pvimg/man/genprotimg.1 b/rust/pvimg/man/genprotimg.1 new file mode 100644 index 00000000..46a91aa4 --- /dev/null +++ b/rust/pvimg/man/genprotimg.1 @@ -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 --output --host-key-document <--no-verify|--cert > +.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 +.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 +.RS 4 +Use the content of FILE as the Linux initial RAM disk. +.RE +.RE +.PP +\-p, \-\-parmfile +.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 +.RS 4 +Write the generated Secure Execution boot image to FILE. +.RE +.RE +.PP +\-k, \-\-host\-key\-document +.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 +.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 +.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 +.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 +.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) diff --git a/rust/pvimg/man/pvimg-create.1 b/rust/pvimg/man/pvimg-create.1 new file mode 100644 index 00000000..aba197fa --- /dev/null +++ b/rust/pvimg/man/pvimg-create.1 @@ -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 --output --host-key-document <--no-verify|--cert > +.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 +.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 +.RS 4 +Use the content of FILE as the Linux initial RAM disk. +.RE +.RE +.PP +\-p, \-\-parmfile +.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 +.RS 4 +Write the generated Secure Execution boot image to FILE. +.RE +.RE +.PP +\-k, \-\-host\-key\-document +.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 +.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 +.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 +.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 +.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) diff --git a/rust/pvimg/man/pvimg-info.1 b/rust/pvimg/man/pvimg-info.1 new file mode 100644 index 00000000..e88cbe49 --- /dev/null +++ b/rust/pvimg/man/pvimg-info.1 @@ -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 +.fam C +.fi +.SH DESCRIPTION +Note that the API and output format is experimental and subject to change. +.SH OPTIONS +.PP + +.RS 4 +Use INPUT as the Secure Execution image. +.RE +.RE + +.PP +\-\-format +.RS 4 +The output format. + +Possible values: +.RS 4 +\- \fBjson\fP: JSON format. + +.RE +.RE +.PP +\-\-key +.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) diff --git a/rust/pvimg/man/pvimg-test.1 b/rust/pvimg/man/pvimg-test.1 new file mode 100644 index 00000000..901c7edb --- /dev/null +++ b/rust/pvimg/man/pvimg-test.1 @@ -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 |--key-hashes[=]> +.fam C +.fi +.SH DESCRIPTION +Test different aspects of an existing IBM Secure Execution image +.SH OPTIONS +.PP + +.RS 4 +Use INPUT as the Secure Execution image. +.RE +.RE + +.PP +\-k, \-\-host\-key\-document +.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[=] +.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) diff --git a/rust/pvimg/man/pvimg.1 b/rust/pvimg/man/pvimg.1 new file mode 100644 index 00000000..37c8e978 --- /dev/null +++ b/rust/pvimg/man/pvimg.1 @@ -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] +.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)