Merge pull request #93507 from mramendi/RHDEVDOCS-6410

RHDEVDOCS 6410 Chains automatic Cosign key pair

Author: xenolinux

modules/op-chains-generating-cosign-secret.adoc

@@ -0,0 +1,70 @@
+// This module is included in the following assemblies:
+// * secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="chains-generating-cosign-secret_{context}"]
+= Generating the cosign key pair by using the TektonConfig CR
+
+To use the `cosign` signing scheme for {tekton-chains} secrets, you can generate a `cosign` key pair that uses ECDSA encryption by setting the `generateSigningSecret` field in the `TektonConfig` custom resource (CR) to `true`.
+
+.Prerequisites
+
+* You installed the {oc-first} utility.
+* You are logged in to your {OCP} cluster with administrative rights for the `openshift-pipelines` namespace.
+
+.Procedure
+
+. Edit the `TektonConfig` CR by running the following command:
++
+[source,terminal]
+----
+$ oc edit TektonConfig config
+----
+
+. In the `TektonConfig` CR, set the `generateSigningSecret` value to `true`:
++
+.Example of creating an ECDSA cosign key pair by using the TektonConfig CR
+[source,yaml]
+----
+apiVersion: operator.tekton.dev/v1
+kind: TektonConfig
+metadata:
+  name: config
+spec:
+# ...
+  chain:
+    disabled: false
+    generateSigningSecret: true # <1>
+# ...
+----
+<1> The default value is `false`. Setting the value to `true` generates the `ecdsa` key pair.
+
+. After a few minutes, extract the public key from the secret and store it, so that you can use it to verify artifact attestations. Run the following command to extract the key:
++
+[source,terminal]
+----
+$ oc extract -n openshift-pipelines secret/signing-secrets --keys=cosign.pub
+----
+
+.Result
+
+The {pipelines-shortname} Operator generates an `ecdsa` type `cosign` key pair and stores it in the `signing-secrets` secret in the `openshift-pipelines` namespace. The secret includes the following files:
+
+* `cosign.key`: The private key
+* `cosign.password`: The password for decrypting the private key
+* `cosign.pub` The public key
+
+If a `signing-secrets` secret already exists, the Operator does not overwrite the secret.
+
+The `cosign.pub` file in your current directory contains the public key that is extracted from the secret.
+
+[WARNING]
+====
+If you set the `generateSigningSecret` field from `true` to `false`, the {pipelines-title} Operator overrides and empties any value in the `signing-secrets` secret.
+====
+
+The {pipelines-title} Operator does not provide the following security functions:
+
+* Key rotation
+* Auditing key usage
+* Proper access control to the key

modules/op-chains-generating-x509-secret.adoc

@@ -4,7 +4,7 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="chains-signing-secrets-cosign_{context}"]
-= Signing with the cosign tool
+= Manually generating signing secrets with the cosign tool
 
 You can use the `cosign` signing scheme with {tekton-chains} using the `cosign` tool.
 

modules/op-chains-signing-secrets-cosign.adoc

@@ -4,13 +4,13 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="chains-signing-secrets-skopeo_{context}"]
-= Signing with the skopeo tool
+= Manually generating signing secrets with the skopeo tool
 
 You can generate keys using the `skopeo` tool and use them in the `cosign` signing scheme with {tekton-chains}.
 
 .Prerequisites
 
-* You installed the link:https://github.com/containers/skopeo[skopeo] tool.
+* You installed the `skopeo` package on your Linux system.
 
 .Procedure
 

modules/op-chains-signing-secrets-skopeo.adoc

@@ -26,7 +26,7 @@ include::modules/op-creating-mounting-kms-authentication-token-secret.adoc[level
 include::modules/op-enabling-tekton-chains-to-operate-only-in-selected-namespaces.adoc[leveloffset=+2]
 
 include::modules/op-signing-secrets-in-tekton-chains.adoc[leveloffset=+1]
-include::modules/op-chains-generating-x509-secret.adoc[leveloffset=+2]
+include::modules/op-chains-generating-cosign-secret.adoc[leveloffset=+2]
 include::modules/op-chains-signing-secrets-cosign.adoc[leveloffset=+2]
 include::modules/op-chains-signing-secrets-skopeo.adoc[leveloffset=+2]
 include::modules/op-chains-resolving-existing-secret.adoc[leveloffset=+2]