diff --git a/rust/Makefile b/rust/Makefile index 5c8c240a..c40e78ce 100644 --- a/rust/Makefile +++ b/rust/Makefile @@ -115,6 +115,7 @@ install-man: $(INSTALL) -m 644 $(target)/man/*.1 -t $(DESTDIR)$(MANDIR)/man1;) $(foreach target,$(PV_TARGETS),\ $(INSTALL) -m 644 $(target)/man/*.1 -t $(DESTDIR)$(MANDIR)/man1;) + ln -sf pvimg-create.1 $(DESTDIR)$(MANDIR)/man1/genprotimg.1 install-shell-completions: install-bash-completion install-zsh-completion diff --git a/rust/pvimg/man/genprotimg.1 b/rust/pvimg/man/genprotimg.1 deleted file mode 100644 index 8168256c..00000000 --- a/rust/pvimg/man/genprotimg.1 +++ /dev/null @@ -1,299 +0,0 @@ -.\" 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-19" "s390-tools" "Genprotimg Manual" -.nh -.ad l -.SH NAME -genprotimg \- Create an IBM Secure Execution image -.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, \-\-image -.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 -\-\-cck, \-\-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 -\-\-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 -\fB\-\-cck\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\-\-cck\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 -\-\-enable\-image\-encryption -.RS 4 -Enable encryption of the image components (default). The image components are: -the kernel, ramdisk, and kernel command line. -.RE -.RE -.PP -\-\-disable\-image\-encryption -.RS 4 -Disable encryption of the image components. The image components are: the -kernel, ramdisk, and kernel command line. Use only if the components used do not -contain any confidential content (for example, secrets like non\-public -cryptographic keys). -.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 \-\-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. -.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. -.IP "4." 4 -With \fBgenprotimg\fR version \fB2.36.0\fR two breaking API changes were -introduced: -.RS -.IP "1." 4 -An existing output file is no longer silently overwritten; to revert to the old -behavior use the \fB\-\-overwrite\fR option. -.IP "2." 4 -The Linux kernel component is now checked to determine whether it is a binary -s390x kernel. To disable this behavior use the \fB\-\-no\-component\-check\fR -option. -.RE -.SH "SEE ALSO" -.sp -\fBpvimg-create\fR(1) \fBzipl\fR(8) \fBqemu\fR(1)