diff --git a/docs/buildah-build.1.md b/docs/buildah-build.1.md index dfd3aaa3c28..b56d1573a77 100644 --- a/docs/buildah-build.1.md +++ b/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,12 +333,6 @@ 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 @@ -336,10 +340,6 @@ 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 diff --git a/docs/buildah-commit.1.md b/docs/buildah-commit.1.md index ac17d0d5ba2..2675caa07a9 100644 --- a/docs/buildah-commit.1.md +++ b/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,12 +84,6 @@ 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 @@ -87,10 +91,6 @@ 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 diff --git a/docs/buildah-mkcw.1.md b/docs/buildah-mkcw.1.md new file mode 100644 index 00000000000..61afe6fa29a --- /dev/null +++ b/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) diff --git a/docs/buildah.1.md b/docs/buildah.1.md index 3ca62b7c14e..1f8bbc5f14e 100644 --- a/docs/buildah.1.md +++ b/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. |