Skip to content

Commit decaca1

Browse files
agantonyagantony
authored
Merge pull request #94078 from agantony/ROX29351-rhacs-docs-main
[RHACS] [Docs] ROX-29351: Adding documentation for keyless verification
2 parents 4194ce5 + 0a2c798 commit decaca1

5 files changed

+171
-58
lines changed

‎modules/common-attributes.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ endif::[]
3434
:rh-storage-first: Red{nbsp}Hat OpenShift Container Storage
3535
:rh-storage: OpenShift Container Storage
3636
:rh-rhacm-first: Red{nbsp}Hat Advanced Cluster Management (RHACM)
37+
:rh-rhtas-first: Red{nbsp}Hat Trusted Artifact Signer (RHTAS)
3738
:rh-rhacs-first: Red{nbsp}Hat Advanced Cluster Security for Kubernetes (RHACS)
3839
:rh-rhacscs-first: Red{nbsp}Hat Advanced Cluster Security Cloud Service (RHACS Cloud Service)
3940
:rh-rhacm: RHACM

‎modules/configure-signature-integration.adoc

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎modules/securing-container-images-by-using-signature-integration.adoc

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operating/verify-image-signatures.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="securing-container-images-by-using-signature-integration_{context}"]
7+
= Securing container images by using signature integration
8+
9+
By creating a signature integration, you can ensure that a trusted source signs the container image.
10+
11+
When you create a signature integration, you can use the following verification methods:
12+
13+
* Cosign public keys
14+
* Cosign certificates
15+
16+
You can also enhance signature verification by enabling transparency log validation.
17+
The transparency log records the signature in a public log and provides cryptographic proof of its inclusion.
18+
You can strengthen verification by adding traceability and increasing trust when you use public keys or certificates.
19+
20+
[IMPORTANT]
21+
====
22+
You must configure at least one trusted signer. To configure a trusted signer, you must specify a Cosign public encryption key or a Cosign certificate chain. You can combine multiple image signers in a single signature integration.
23+
====
24+
25+
.Prerequisites
26+
27+
* You have a Cosign public key which is encoded in Privacy Enhanced Mail (PEM) format.
28+
+
29+
For more information about Cosign public keys, see link:https://docs.sigstore.dev/cosign/signing/overview/[Overview] (Sigstore documentation).
30+
31+
* You have the certificate identity and issuer.
32+
* Optional: You have a certificate and chain which is encoded in PEM format.
33+
+
34+
For more information about Cosign certificates, see link:https://docs.sigstore.dev/cosign/verifying/verify/[Verifying Signatures] (Sigstore documentation).
35+
36+
.Procedure
37+
38+
. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*.
39+
. Scroll down to the *Signature Integrations* section, and then click *Signature*.
40+
. To create a new signature integration, click *New integration*.
41+
. Enter a name for the integration.
42+
. To add a new public key, complete the following steps:
43+
+
44+
[NOTE]
45+
====
46+
** If you add a public key, you do not need to create a new certificate verification.
47+
** You can add one or more public keys.
48+
====
49+
.. Expand *Cosign public Keys*, and then click *Add new public key*.
50+
.. Enter a name for the key.
51+
.. Enter a value for the key which is encoded in PEM format.
52+
. To add a new certificate verification, complete the following steps:
53+
+
54+
[IMPORTANT]
55+
====
56+
** When you create a signature integration, you must add a new certificate verification if you want to use keyless verification for the image signature by using {rh-rhtas-first}.
57+
** You can add one or more certificate verifications.
58+
====
59+
.. Expand *Cosign certificates*, and then click *Add new certificate verification*.
60+
.. Enter the certificate OIDC issuer that Cosign specifies. You must use regular expressions in RE2 syntax for matching.
61+
+
62+
For more information, go to the GitHub repository at `google/re2`, open the `Wiki` section, and then select the `Syntax` page.
63+
.. Enter the certificate identity that Cosign specifies. You must use regular expressions in RE2 syntax for matching.
64+
+
65+
For more information, go to the GitHub repository at `google/re2`, open the `Wiki` section, and then select the `Syntax` page.
66+
.. Enter the trusted certificate root which is encoded in PEM format to verify the certificates. If you do not specify the certificate root, the public Fulcio roots are used automatically for verification.
67+
+
68+
For more information, see link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio] (Sigstore documentation).
69+
.. Enter the trusted signer intermediate certificate authority to verify the certificates. If you do not specify the certificate authority, the certificate chain is used automatically for verification.
70+
.. Optional: Select the *Enable certificate transparency log validation* checkbox to validate the proof of inclusion into the certificate transparency log.
71+
+
72+
Enter the public key that you want to use to validate the proof of inclusion into the certificate transparency log.
73+
If you do not specify the public key, the key of the public Sigstore instance is used automatically for validation.
74+
. To configure the transparency log, complete the following steps:
75+
+
76+
[NOTE]
77+
====
78+
When you create a signature integration, you can enable the validation of transparency logs in the following situations:
79+
80+
** When the signatures contain short-lived certificates that Fulcio issues.
81+
** When you want to use keyless verification of the signatures.
82+
** To verify the signatures, when you use a public key.
83+
====
84+
.. Select the *Enable transparency log validation* checkbox to validate the inclusion of the signature in a transparency log.
85+
+
86+
Enter the URL where the Rekor transparency log is available. If you do not specify the URL, the public Rekor instance of Sigstore is used automatically for validation.
87+
+
88+
[NOTE]
89+
====
90+
The Rekor URL is required for online confirmation of the inclusion into the transparency log.
91+
====
92+
.. Optional: Select the *Validate in offline mode* checkbox to force the offline validation of the signature proof of inclusion into the transparency log.
93+
+
94+
[NOTE]
95+
====
96+
You can force the offline validation of the signature proof of inclusion into the transparency log only if you have enabled the validation of the transparency log.
97+
====
98+
+
99+
Enter the public key to validate the signature proof of inclusion into the Rekor transparency log.
100+
If you do not specify the public key, the key of the public Sigstore instance is used automatically for validation.
101+
. Click *Save*.
102+
103+
.Verification
104+
105+
. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*.
106+
. Scroll down to the *Signature Integrations* section, and then click *Signature*.
107+
. Verify that the creation of the signature integration was successful.
108+
. Optional: Choose the appropriate method to manage the signature integration that you have created:
109+
** To delete the signature integration, click the overflow menu {kebab} and then select *Delete Integration*.
110+
** To edit the signature integration, click the overflow menu {kebab} and then select *Edit Integration*.

‎modules/verifying-image-signatures-to-ensure-image-integrity.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operating/verify-image-signatures.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="verifying-image-signatures-to-ensure-image-integrity_{context}"]
7+
= Verifying image signatures to ensure image integrity
8+
9+
To verify image integrity, you must check that a trusted source signed the image.
10+
If you have enabled transparency log validation for your signature integration, you must also confirm that the scan includes a valid transparency log bundle.
11+
12+
For multi-architecture images, you must sign both the index and architecture-specific digests to avoid runtime resolution issues.
13+
14+
.Prerequisites
15+
16+
* You have created a signature integration.
17+
+
18+
For more information about how to create a signature integration, see "Securing container Images by using signature integration".
19+
20+
.Procedure
21+
22+
* To scan an image signature by using the `roxctl` CLI, run the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ roxctl image scan \
27+
--image=<registry>/<repository>/<image>@<digest> \
28+
--force-insecure-skip-tls-verify
29+
----
30+
+
31+
where:
32+
+
33+
--
34+
`<registry>`:: Specifies the container image registry. For example, `quay.io`.
35+
`<repository>`:: Specifies the repository of the container image. For example, `quay`.
36+
`<image>`:: Specifies the name of the container image that you want to scan. For example, `busybox`.
37+
`<digest>`:: Specifies the digest of the container image. For example, `sha256:92f3298bf80a1ba949140d77987f5de081f010337880cd771f7e7fc928f8c74d`.
38+
--
39+
+
40+
Verify that the output includes the signature.
41+
If transparency log validation is enabled for your signature integration, verify that the output includes the Rekor bundle with the proof of inclusion into the transparency log.
42+
+
43+
If certificate verification is enabled for your signature integration, verify that the output includes the certificate verification data.

‎operating/verify-image-signatures.adoc

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,30 @@ You can also enforce the policy by using the {product-title-short} admission con
1313

1414
[NOTE]
1515
====
16-
* {product-title-short} only supports Cosign signatures and Cosign Public Keys/Certificates verification. For more information about Cosign, see link:https://docs.sigstore.dev/cosign/overview[Cosign overview].
17-
* For Cosign signature verification, {product-title-short} does not support communication with the transparency log link:https://docs.sigstore.dev/logging/overview/[Rekor].
16+
* {product-title-short} supports Cosign signature verification by using Cosign public keys, Cosign certificates, or both.
17+
+
18+
For more information about Cosign, see link:https://docs.sigstore.dev/cosign/signing/overview/[Overview] (Sigstore documentation).
19+
* For Cosign signature verification, {product-title-short} supports communication with the transparency log.
20+
+
21+
For more information, see link:https://docs.sigstore.dev/logging/overview/[Rekor] (Sigstore documentation).
22+
* For Cosign signature verification, you can use keyless verification with {product-title-short}. If you want to host the key infrastructure yourself, you can do this by using {rh-rhtas-first}.
1823
* You must configure signature integration with at least 1 Cosign verification method for signature verification.
1924
* For all deployed and watched images:
2025
** {product-title-short} fetches and verifies the signatures every 4 hours.
2126
** {product-title-short} verifies the signatures whenever you change or update your signature integration verification data.
2227
====
2328

24-
//Configuring signature integration
25-
include::modules/configure-signature-integration.adoc[leveloffset=+1]
29+
//Securing container images by using signature integration
30+
include::modules/securing-container-images-by-using-signature-integration.adoc[leveloffset=+1]
2631

27-
//Using signature verification
32+
//Verifying image signatures to ensure image integrity
33+
include::modules/verifying-image-signatures-to-ensure-image-integrity.adoc[leveloffset=+1]
34+
35+
[role="_additional-resources"]
36+
.Additional resources
37+
* xref:../operating/verify-image-signatures.adoc#securing-container-images-by-using-signature-integration_verify-image-signatures[Securing container images by using signature integration]
38+
39+
//Using signature verification in a policy
2840
include::modules/use-signature-verification.adoc[leveloffset=+1]
2941

3042
[role="_additional-resources"]

0 commit comments

Comments
 (0)