From 651fe74ab7ea514729fb921d4c58f7b8b07fd307 Mon Sep 17 00:00:00 2001 From: subhtk Date: Tue, 29 Apr 2025 13:10:47 +0530 Subject: [PATCH] Added signature mirroring and verification section in oc-mirror plugin v2 --- .../about-installing-oc-mirror-v2.adoc | 5 ++ modules/oc-mirror-command-reference-v2.adoc | 12 ++++ ...-mirror-signature-mirroring-procedure.adoc | 59 +++++++++++++++++++ modules/oc-mirror-signature-mirroring.adoc | 9 +++ modules/oc-mirror-signature-verification.adoc | 51 ++++++++++++++++ 5 files changed, 136 insertions(+) create mode 100644 modules/oc-mirror-signature-mirroring-procedure.adoc create mode 100644 modules/oc-mirror-signature-mirroring.adoc create mode 100644 modules/oc-mirror-signature-verification.adoc diff --git a/disconnected/mirroring/about-installing-oc-mirror-v2.adoc b/disconnected/mirroring/about-installing-oc-mirror-v2.adoc index 414bb5f559..fe0126105d 100644 --- a/disconnected/mirroring/about-installing-oc-mirror-v2.adoc +++ b/disconnected/mirroring/about-installing-oc-mirror-v2.adoc @@ -118,6 +118,11 @@ include::modules/oc-mirror-proxy-support.adoc[leveloffset=+1] * xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service] * xref:../../disconnected/mirroring/about-installing-oc-mirror-v2.adoc#oc-mirror-v2-procedure-garbage-collector_about-installing-oc-mirror-v2[Resolving storage cleanup issues in the distribution registry] +//signature mirroring +include::modules/oc-mirror-signature-mirroring.adoc[leveloffset=+1] +include::modules/oc-mirror-signature-mirroring-procedure.adoc[leveloffset=+2] +include::modules/oc-mirror-signature-verification.adoc[leveloffset=+2] + // Operator catalog filtering include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1] diff --git a/modules/oc-mirror-command-reference-v2.adoc b/modules/oc-mirror-command-reference-v2.adoc index 83e23e403f..5a56d34450 100644 --- a/modules/oc-mirror-command-reference-v2.adoc +++ b/modules/oc-mirror-command-reference-v2.adoc @@ -98,4 +98,16 @@ The following tables describe the `oc mirror` subcommands and flags for oc-mirro |`--rootless-storage-path ` |Overrides the default container rootless storage path (usually in `etc/containers/storage.conf`). +|`--remove-signatures` +|Does not copy signatures from the source image. + +|`--registries.d` +|Specifies the directory that contains registry configuration files. + +|`--secure-policy=true` +|Enables signature verification for all images. + +|`--policy` +|Specifies the path to the signature verification policy file. + |=== \ No newline at end of file diff --git a/modules/oc-mirror-signature-mirroring-procedure.adoc b/modules/oc-mirror-signature-mirroring-procedure.adoc new file mode 100644 index 0000000000..f3b323abaa --- /dev/null +++ b/modules/oc-mirror-signature-mirroring-procedure.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oc-mirror-signature-mirroring-procedure_{context}"] += Enabling signature mirroring for oc-mirror plugin v2 + +By default, signature mirroring is disabled. You can enable signature mirroring for all images by setting the `--remove-signatures=false` flag for the `oc mirror` command. + +When enabled, the oc-mirror plugin v2 mirrors `Sigstore` tag-based signatures for the following images: + +* {product-title} release images +* Operator images +* Additional images +* Helm charts + +[NOTE] +==== +If you do not provide a configuration file, the oc-mirror plugin v2 enables signature mirroring for all images by default when the `--remove-signatures=false` flag is used. + +To specify a custom configuration directory, use the `--registries.d` flag. + +For more details, see the link:https://github.com/containers/image/blob/main/docs/containers-registries.d.5.md[`containers-registries.d(5)`] manual. +==== + +.Procedure + +. If you want to enable signature mirroring for all images, run the following command: ++ +[source,terminal] +---- +$ oc mirror --remove-signatures=false +---- + +. If you want to enable or disable signature mirroring for specific elements, such as transport protocol, registry, namespace or image, use the following steps: + +.. Create a YAML file in either the `$HOME/.config/containers/registries.d/` or `/etc/containers/registries.d/` directory. + +.. Specify the `use-sigstore-attachments` parameter and set it to either `true` or `false` under the specific element you want to control, as seen in the following examples: ++ +.Example: Disable signature mirroring for the `quay.io` registry +[source,yaml] +---- +# ... +docker: + quay.io: + use-sigstore-attachments: false +# ... +---- ++ +.Example: Enable signature mirroring for all registries +[source,yaml] +---- +# ... +default-docker: + use-sigstore-attachments: true +# ... +---- diff --git a/modules/oc-mirror-signature-mirroring.adoc b/modules/oc-mirror-signature-mirroring.adoc new file mode 100644 index 0000000000..20fa1e833e --- /dev/null +++ b/modules/oc-mirror-signature-mirroring.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-mirror-signature-mirroring_{context}"] += Mirroring and verifying image signatures in oc-mirror plugin v2 + +Starting with {product-title} 4.19, the oc-mirror plugin v2 supports mirroring and verifying cosign tag-based signatures for container images. \ No newline at end of file diff --git a/modules/oc-mirror-signature-verification.adoc b/modules/oc-mirror-signature-verification.adoc new file mode 100644 index 0000000000..b55678a138 --- /dev/null +++ b/modules/oc-mirror-signature-verification.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oc-mirror-about-sig-mirroring-verification_{context}"] += Enabling signature verification for oc-mirror plugin v2 + +Starting with {product-title} 4.19, the oc-mirror plugin v2 supports signature verification, which is disabled by default. When enabled, the plugin verifies that container images match their signatures, ensuring they have not been altered and come from trusted sources. If a signature mismatch is detected, the mirroring workflow will fail. + +.Procedure + +. If you want to enable signature verification for all images, run the following command: ++ +[source,terminal] +---- +$ oc mirror --secure-policy=true +---- + +. If you want to enable or disable signature verification for specific elements — such as a transport protocol, registry, namespace, or image — follow these steps: + +.. Create a `policy.json` file in either the `$HOME/.config/containers/` or `/etc/containers/` directory. ++ +[NOTE] +==== +If your policy configuration file is located outside the default directory, you can specify its path by using the `--policy` flag with the `oc mirror` command. + +For more information, see link:https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md[`containers-policy.json(5)`]. +==== + +.. Define verification rules for the desired scope (for example, registry or image) using the appropriate policy configuration. You can set the verification requirement by specifying the desired rule under each element. ++ +.Example: Enable verification for only a specific image, and reject all other images ++ +[source,json] +---- +{ + "default": [{"type": "reject"}], + "transports": { + "docker": { + "hostname:5000/myns/sigstore-signed-image": [ + { + "type": "sigstoreSigned", + "keyPath": "/path/to/sigstore-pubkey.pub", + "signedIdentity": {"type": "matchRepository"} + } + ] + } + } +} +---- \ No newline at end of file