Add some docs for build --cw, commit --cw, and mkcw

Add docs for the new --cw option recognized by both `commit` and
`build`, and the new `mkcw` command.

Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>

docs/buildah-build.1.md

@@ -312,6 +312,16 @@ If no value is specified, a *passphrase* value *must* be specified.
 *cpus*: The number of virtual CPUs which the image expects to be run with at
 run-time.  If not specified, a default value will be supplied.
 
+*encryption_passphrase*: The passphrase to use to encrypt the disk image which will be
+included in the container image.
+If no value is specified, but an *attestation_url* value is specified, a
+randomly-generated passphrase will be used.
+The authors recommend setting an *attestation_url* but not an *encryption_passphrase*.
+
+*firmware_library*: The location of the libkrunfw-sev shared library.  If not
+specified, `buildah` checks for its presence in a number of hard-coded
+locations.
+
 *ignore_attestation_errors*: Ignore error responses from the key broker /
 attestation server, problems contacting it, or errors reported when invoking
 *krunfw\_measurement* to measure the host's trusted execution environment.
@@ -323,23 +333,13 @@ to obtain the certificate chain for the local system.
 run-time, as a number of megabytes.  If not specified, a default value will be
 supplied.
 
-*passphrase*: The passphrase to use to encrypt the disk image which will be
-included in the container image.
-If no value is specified, but an *attestation_url* value is specified, a
-randomly-generated passphrase will be used.
-The authors recommend setting an *attestation_url* but not a *passphrase*.
-
 *slop*: Extra space to allocate for the disk image compared to the size of the
 container image's contents, expressed either as a percentage (..%) or a size
 value (bytes, or larger units if suffixes like KB or MB are present), or a sum
 of two or more such specifications.  If not specified, `buildah` guesses that
 25% more space than the contents will be enough, but this option is provided in
 case its guess is wrong.
 
-*firmware_library*: The location of the libkrunfw-sev shared library.  If not
-specified, `buildah` checks for its presence in a number of hard-coded
-locations.
-
 *type*: The type of trusted execution environment (TEE) which the image should
 be marked for use with.  Accepted values are "SEV" (AMD Secure Encrypted
 Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted

docs/buildah-commit.1.md

@@ -63,6 +63,16 @@ If no value is specified, a *passphrase* value *must* be specified.
 *cpus*: The number of virtual CPUs which the image expects to be run with at
 run-time.  If not specified, a default value will be supplied.
 
+*encryption_passphrase*: The passphrase to use to encrypt the disk image which will be
+included in the container image.
+If no value is specified, but an *attestation_url* value is specified, a
+randomly-generated passphrase will be used.
+The authors recommend setting an *attestation_url* but not an *encryption_passphrase*.
+
+*firmware_library*: The location of the libkrunfw-sev shared library.  If not
+specified, `buildah` checks for its presence in a number of hard-coded
+locations.
+
 *ignore_attestation_errors*: Ignore error responses from the key broker /
 attestation server, problems contacting it, or errors reported when invoking
 *krunfw\_measurement* to measure the host's trusted execution environment.
@@ -74,23 +84,13 @@ to obtain the certificate chain for the local system.
 run-time, as a number of megabytes.  If not specified, a default value will be
 supplied.
 
-*passphrase*: The passphrase to use to encrypt the disk image which will be
-included in the container image.
-If no value is specified, but an *attestation_url* value is specified, a
-randomly-generated passphrase will be used.
-The authors recommend setting an *attestation_url* but not a *passphrase*.
-
 *slop*: Extra space to allocate for the disk image compared to the size of the
 container image's contents, expressed either as a percentage (..%) or a size
 value (bytes, or larger units if suffixes like KB or MB are present), or a sum
 of two or more such specifications.  If not specified, `buildah` guesses that
 25% more space than the contents will be enough, but this option is provided in
 case its guess is wrong.
 
-*firmware_library*: The location of the libkrunfw-sev shared library.  If not
-specified, `buildah` checks for its presence in a number of hard-coded
-locations.
-
 *type*: The type of trusted execution environment (TEE) which the image should
 be marked for use with.  Accepted values are "SEV" (AMD Secure Encrypted
 Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted

docs/buildah-mkcw.1.md

@@ -0,0 +1,83 @@
+# buildah-mkcw "1" "July 2023" "buildah"
+
+## NAME
+buildah\-mkcw - Convert a conventional container image into a confidential workload image.
+
+## SYNOPSIS
+**buildah mkcw** [*options*] *source* *destination*
+
+## DESCRIPTION
+Converts the contents of a container image into a new container image which is
+suitable for use in a trusted execution environment (TEE).
+
+## source
+A container image, stored locally or in a registry
+
+## destination
+A container image, stored locally or in a registry
+
+## OPTIONS
+
+**--attestation-url**, **-u** *url*
+The location of a key broker / attestation server.
+If a value is specified, the new image's workload ID, along with the passphrase
+used to encrypt the disk image, will be registered with the server, and the
+server's location will be stored in the container image.
+At run-time, krun is expected to contact the server to retrieve the passphrase
+using the workload ID, which is also stored in the container image.
+If no value is specified, an *encryption-passphrase* value *must* be specified.
+
+**--base-image**, **-b** *image*
+An alternate image to use as the base for the output image.  By default,
+the *scratch* non-image is used.
+
+**--cpus**, **-c** *number*
+The number of virtual CPUs which the image expects to be run with at run-time.
+If not specified, a default value will be supplied.
+
+**--encryption-passphrase**, **-p** *text*
+The passphrase to use to encrypt the disk image which will be included in the
+container image.
+If no value is specified, but a *--attestation-url* value is specified, a
+randomly-generated passphrase will be used.
+The authors recommend setting a *--attestation-url* but not an *--encryption-passphrase*.
+
+**--firmware-library**, **-f** *file*
+The location of the libkrunfw-sev shared library.  If not specified, `buildah`
+checks for its presence in a number of hard-coded locations.
+
+**--ignore-attestation-errors**[=*true*]
+Ignore error responses from the key broker / attestation server, problems
+contacting it, or errors reported when invoking *krunfw\_measurement* to
+measure the host's trusted execution environment.
+
+**--ignore-chain-retrieval-errors**[=*true*]
+Ignore errors reported when invoking *sevctl* to obtain the certificate chain
+for the local system.
+
+**--memory**, **-m** *number*
+The amount of memory which the image expects to be run with at run-time, as a
+number of megabytes.  If not specified, a default value will be supplied.
+
+**--slop**, **-s** *{percentage%|sizeKB|sizeMB|sizeGB}*
+Extra space to allocate for the disk image compared to the size of the
+container image's contents, expressed either as a percentage (..%) or a size
+value (bytes, or larger units if suffixes like KB or MB are present), or a sum
+of two or more such specifications.  If not specified, `buildah` guesses that
+25% more space than the contents will be enough, but this option is provided in
+case its guess is wrong.
+
+**--type**, **-t** {SEV|SNP}
+The type of trusted execution environment (TEE) which the image should be
+marked for use with.  Accepted values are "SEV" (AMD Secure Encrypted
+Virtualization - Encrypted State) and "SNP" (AMD Secure Encrypted
+Virtualization - Secure Nested Paging).  If not specified, defaults to "SEV".
+
+**--workload-id**, **-w** *id*
+A workload identifier which will be recorded in the container image, to be used
+at run-time for retrieving the passphrase which was used to encrypt the disk
+image.  If not specified, a semi-random value will be derived from the base
+image's image ID.
+
+## SEE ALSO
+buildah(1)

docs/buildah.1.md

@@ -158,6 +158,7 @@ Buildah can set up environment variables from the env entry in the [engine] tabl
 | login      | [buildah-login(1)](buildah-login.1.md)           | Login to a container registry.                                                                       |
 | logout     | [buildah-logout(1)](buildah-logout.1.md)         | Logout of a container registry                                                                       |
 | manifest   | [buildah-manifest(1)](buildah-manifest.1.md)     | Create and manipulate manifest lists and image indexes.                                              |
+| mkcw       | [buildah-mkcw(1)](buildah-mkcw.1.md)             | Convert a conventional container image into a confidential workload image.
 | mount      | [buildah-mount(1)](buildah-mount.1.md)           | Mount the working container's root filesystem.                                                       |
 | prune      | [buildah-prune(1)](buildah-prune.1.md)           | Cleanup intermediate images as well as build and mount cache.                                        |
 | pull       | [buildah-pull(1)](buildah-pull.1.md)             | Pull an image from the specified location.                                                           |