Skip to content

Commit 651fe74

Browse files
subhtksubhtk
committed
Added signature mirroring and verification section in oc-mirror plugin v2
1 parent e0997f4 commit 651fe74

5 files changed

+136
-0
lines changed

‎disconnected/mirroring/about-installing-oc-mirror-v2.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,11 @@ include::modules/oc-mirror-proxy-support.adoc[leveloffset=+1]
118118
* xref:../../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
119119
* 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]
120120

121+
//signature mirroring
122+
include::modules/oc-mirror-signature-mirroring.adoc[leveloffset=+1]
123+
include::modules/oc-mirror-signature-mirroring-procedure.adoc[leveloffset=+2]
124+
include::modules/oc-mirror-signature-verification.adoc[leveloffset=+2]
125+
121126
// Operator catalog filtering
122127
include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1]
123128

‎modules/oc-mirror-command-reference-v2.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,16 @@ The following tables describe the `oc mirror` subcommands and flags for oc-mirro
9898
|`--rootless-storage-path <string>`
9999
|Overrides the default container rootless storage path (usually in `etc/containers/storage.conf`).
100100

101+
|`--remove-signatures`
102+
|Does not copy signatures from the source image.
103+
104+
|`--registries.d`
105+
|Specifies the directory that contains registry configuration files.
106+
107+
|`--secure-policy=true`
108+
|Enables signature verification for all images.
109+
110+
|`--policy`
111+
|Specifies the path to the signature verification policy file.
112+
101113
|===

‎modules/oc-mirror-signature-mirroring-procedure.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oc-mirror-signature-mirroring-procedure_{context}"]
7+
= Enabling signature mirroring for oc-mirror plugin v2
8+
9+
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.
10+
11+
When enabled, the oc-mirror plugin v2 mirrors `Sigstore` tag-based signatures for the following images:
12+
13+
* {product-title} release images
14+
* Operator images
15+
* Additional images
16+
* Helm charts
17+
18+
[NOTE]
19+
====
20+
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.
21+
22+
To specify a custom configuration directory, use the `--registries.d` flag.
23+
24+
For more details, see the link:https://github.com/containers/image/blob/main/docs/containers-registries.d.5.md[`containers-registries.d(5)`] manual.
25+
====
26+
27+
.Procedure
28+
29+
. If you want to enable signature mirroring for all images, run the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ oc mirror --remove-signatures=false
34+
----
35+
36+
. If you want to enable or disable signature mirroring for specific elements, such as transport protocol, registry, namespace or image, use the following steps:
37+
38+
.. Create a YAML file in either the `$HOME/.config/containers/registries.d/` or `/etc/containers/registries.d/` directory.
39+
40+
.. 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:
41+
+
42+
.Example: Disable signature mirroring for the `quay.io` registry
43+
[source,yaml]
44+
----
45+
# ...
46+
docker:
47+
quay.io:
48+
use-sigstore-attachments: false
49+
# ...
50+
----
51+
+
52+
.Example: Enable signature mirroring for all registries
53+
[source,yaml]
54+
----
55+
# ...
56+
default-docker:
57+
use-sigstore-attachments: true
58+
# ...
59+
----

‎modules/oc-mirror-signature-mirroring.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="oc-mirror-signature-mirroring_{context}"]
7+
= Mirroring and verifying image signatures in oc-mirror plugin v2
8+
9+
Starting with {product-title} 4.19, the oc-mirror plugin v2 supports mirroring and verifying cosign tag-based signatures for container images.

‎modules/oc-mirror-signature-verification.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oc-mirror-about-sig-mirroring-verification_{context}"]
7+
= Enabling signature verification for oc-mirror plugin v2
8+
9+
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.
10+
11+
.Procedure
12+
13+
. If you want to enable signature verification for all images, run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc mirror --secure-policy=true
18+
----
19+
20+
. If you want to enable or disable signature verification for specific elements — such as a transport protocol, registry, namespace, or image — follow these steps:
21+
22+
.. Create a `policy.json` file in either the `$HOME/.config/containers/` or `/etc/containers/` directory.
23+
+
24+
[NOTE]
25+
====
26+
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.
27+
28+
For more information, see link:https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md[`containers-policy.json(5)`].
29+
====
30+
31+
.. 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.
32+
+
33+
.Example: Enable verification for only a specific image, and reject all other images
34+
+
35+
[source,json]
36+
----
37+
{
38+
"default": [{"type": "reject"}],
39+
"transports": {
40+
"docker": {
41+
"hostname:5000/myns/sigstore-signed-image": [
42+
{
43+
"type": "sigstoreSigned",
44+
"keyPath": "/path/to/sigstore-pubkey.pub",
45+
"signedIdentity": {"type": "matchRepository"}
46+
}
47+
]
48+
}
49+
}
50+
}
51+
----

0 commit comments

Comments
 (0)