From 8e0501dee13d95056f116c80936bf090e7237c8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Tue, 5 Dec 2023 14:54:44 -0500 Subject: [PATCH] OCPBUGS-19749: add verification for unsigned containers --- .../containers-signature-verify-skopeo.adoc | 74 +++++++++++++++++++ .../containers-signature-verify-unsigned.adoc | 26 +++++++ .../security-container-signature.adoc | 12 +++ 3 files changed, 112 insertions(+) create mode 100644 modules/containers-signature-verify-skopeo.adoc create mode 100644 modules/containers-signature-verify-unsigned.adoc diff --git a/modules/containers-signature-verify-skopeo.adoc b/modules/containers-signature-verify-skopeo.adoc new file mode 100644 index 0000000000..52aa91f654 --- /dev/null +++ b/modules/containers-signature-verify-skopeo.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// * security/container_security/security-container-signature.adoc + +:_mod-docs-content-type: PROCEDURE +[id="containers-signature-verify-skopeo_{context}"] += Using skopeo to verify signatures of Red Hat container images + +You can verify the signatures for container images included in an {product-title} release image by pulling those signatures from link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift-release-dev/ocp-release/[OCP release mirror site]. Because the signatures on the mirror site are not in a format readily understood by Podman or CRI-O, you can use the `skopeo standalone-verify` command to verify that the your release images are signed by Red Hat. + +.Prerequisites + +* You have installed the `skopeo` command-line utility. + +.Procedure + +. Get the full SHA for your release by running the following command: ++ +[source,terminal] +---- +$ oc adm release info \ <1> +---- +<1> Substitute with your release number, for example, `4.14.3`. ++ +.Example output snippet ++ +[source,terminal] +---- +--- +Pull From: quay.io/openshift-release-dev/ocp-release@sha256:e73ab4b33a9c3ff00c9f800a38d69853ca0c4dfa5a88e3df331f66df8f18ec55 +--- +---- + +. Pull down the Red Hat release key by running the following command: ++ +[source,terminal] +---- +$ curl -o pub.key https://access.redhat.com/security/data/fd431d51.txt +---- + +. Get the signature file for the specific release that you want to verify by running the following command: ++ +[source,terminal] +---- +$ curl -o signature-1 https://mirror.openshift.com/pub/openshift-v4/signatures/openshift-release-dev/ocp-release/sha256%/signature-1 \ <1> +---- +<1> Replace `` with SHA value from the full link to the mirror site that matches the SHA of your release. For example, the link to the signature for the 4.12.23 release is `https://mirror.openshift.com/pub/openshift-v4/signatures/openshift-release-dev/ocp-release/sha256%e73ab4b33a9c3ff00c9f800a38d69853ca0c4dfa5a88e3df331f66df8f18ec55/signature-1`, and the SHA value is `e73ab4b33a9c3ff00c9f800a38d69853ca0c4dfa5a88e3df331f66df8f18ec55`. + +. Get the manifest for the release image by running the following command: ++ +[source,terminal] +---- +$ skopeo inspect --raw docker:// > manifest.json \ <1> +---- +<1> Replace `` with the output of the `oc adm release info` command. For example, `quay.io/openshift-release-dev/ocp-release@sha256:e73ab4b33a9c3ff00c9f800a38d69853ca0c4dfa5a88e3df331f66df8f18ec55`. + +. Use skopeo to verify the signature: ++ +[source,terminal] +---- +$ skopeo standalone-verify manifest.json quay.io/openshift-release-dev/ocp-release:- any signature-1 --public-key-file pub.key +---- ++ +where: ++ +``:: Specifies the release number, for example `4.14.3`. +``:: Specifies the architecture, for example `x86_64`. ++ +.Example output +[source,terminal] +---- +Signature verified using fingerprint 567E347AD0044ADE55BA8A5F199E2F91FD431D51, digest sha256:e73ab4b33a9c3ff00c9f800a38d69853ca0c4dfa5a88e3df331f66df8f18ec55 +---- + diff --git a/modules/containers-signature-verify-unsigned.adoc b/modules/containers-signature-verify-unsigned.adoc new file mode 100644 index 0000000000..45745d7a0d --- /dev/null +++ b/modules/containers-signature-verify-unsigned.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * security/container_security/security-container-signature.adoc + +:_mod-docs-content-type: CONCEPT +[id="containers-signature-verify-artifacts_{context}"] += Understanding the verification of container images lacking verifiable signatures +Each {product-title} release image is immutable and signed with a Red Hat production key. During an {product-title} update or installation, a release image might deploy container images that do not have verifiable signatures. Each signed release image digest is immutable. Each reference in the release image is to the immutable digest of another image, so the contents can be trusted transitively. In other words, the signature on the release image validates all release contents. + +For example, the image references lacking a verifiable signature are contained in the signed {product-title} release image: + +.Example release info output +[source,terminal] +---- +$ oc adm release info quay.io/openshift-release-dev/ ocp-release@sha256:2309578b68c5666dad62aed696f1f9d778ae1a089ee461060ba7b9514b7ca417 -o pullspec <1> +quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:9aafb914d5d7d0dec4edd800d02f811d7383a7d49e500af548eab5d00c1bffdb <2> +---- + +<1> Signed release image SHA. +<2> Container image lacking a verifiable signature included in the release. + +[id="containers-signature-verification-automatic_{context}"] +== Automated verification during updates +Verification of signatures is automatic. The OpenShift Cluster Version Operator (CVO) verifies signatures on the release images during an {product-title} update. This is an internal process. An {product-title} installation or update fails if the automated verification fails. + +Verification of signatures can also be done manually using the `skopeo` command-line utility. \ No newline at end of file diff --git a/security/container_security/security-container-signature.adoc b/security/container_security/security-container-signature.adoc index 5f7f1b3d39..d5f9937e86 100644 --- a/security/container_security/security-container-signature.adoc +++ b/security/container_security/security-container-signature.adoc @@ -18,6 +18,18 @@ include::modules/containers-signature-verify-enable.adoc[leveloffset=+1] //Verifying that the enable signature verification is active include::modules/containers-signature-verify-application.adoc[leveloffset=+1] +//Understanding the verification of container images lacking verifiable signatures +include::modules/containers-signature-verify-unsigned.adoc[leveloffset=+1] + +//additional resources for unsigned container module +[id="additional-resources"] +[role="_additional-resources"] +.Additional resources +* xref:../../updating/understanding_updates/intro-to-updates.adoc#understanding-openshift-updates[Introduction to OpenShift Updates] + +//Using skopeo to verify signatures of Red Hat container images +include::modules/containers-signature-verify-skopeo.adoc[leveloffset=+2] + [id="additional-resources_security-container-signature"] [role="_additional-resources"] == Additional resources