diff --git a/modules/op-chains-generating-cosign-secret.adoc b/modules/op-chains-generating-cosign-secret.adoc new file mode 100644 index 000000000000..6f74ecd2cd53 --- /dev/null +++ b/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 diff --git a/modules/op-chains-generating-x509-secret.adoc b/modules/op-chains-generating-x509-secret.adoc deleted file mode 100644 index dd5515c762d5..000000000000 --- a/modules/op-chains-generating-x509-secret.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// 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-x509-secret_{context}"] -= Generating the x509 key pair by using the TektonConfig CR - -To use the `x509` signing scheme for {tekton-chains} secrets, you must generate the `x509` key pair. - -You can generate the `x509` key pair by setting the `generateSigningSecret` field in the `TektonConfig` custom resource (CR) to `true`. -The {pipelines-title} Operator generates an `ecdsa` type key pair: an `x509.pem` private key and an `x509-pub.pem` public key. The Operator stores the keys in the `signing-secrets` secret in the `openshift-pipelines` namespace. - -[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. Ensure that you store the `x509-pub.pem` public key outside of the secret to protect the key from the deletion. The Operator can use the key at a later stage to verify artifact attestations. -==== - -The {pipelines-title} Operator does not provide the following functions to limit potential security issues: - -* Key rotation -* Auditing key usage -* Proper access control to the key - -.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 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. diff --git a/modules/op-chains-signing-secrets-cosign.adoc b/modules/op-chains-signing-secrets-cosign.adoc index e1568331db01..3bac3524b2df 100644 --- a/modules/op-chains-signing-secrets-cosign.adoc +++ b/modules/op-chains-signing-secrets-cosign.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. diff --git a/modules/op-chains-signing-secrets-skopeo.adoc b/modules/op-chains-signing-secrets-skopeo.adoc index cd99d92112fd..a2f84d28a6be 100644 --- a/modules/op-chains-signing-secrets-skopeo.adoc +++ b/modules/op-chains-signing-secrets-skopeo.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 diff --git a/secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc b/secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc index ffaecc12e1b9..93d708d96e2e 100644 --- a/secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc +++ b/secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.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]