From b250fca5c81cf97de51c3f014b03bf8b23d609b9 Mon Sep 17 00:00:00 2001 From: Sanskar Jaiswal Date: Thu, 5 Oct 2023 17:39:24 +0530 Subject: [PATCH] docs: add docs for cosign identity matching Signed-off-by: Sanskar Jaiswal --- docs/spec/v1beta2/helmcharts.md | 11 +++++++++++ docs/spec/v1beta2/ocirepositories.md | 13 +++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/spec/v1beta2/helmcharts.md b/docs/spec/v1beta2/helmcharts.md index 5e98c70bb..c422b185f 100644 --- a/docs/spec/v1beta2/helmcharts.md +++ b/docs/spec/v1beta2/helmcharts.md @@ -307,6 +307,14 @@ For publicly available HelmCharts, which are signed using the [Cosign Keyless](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) procedure, you can enable the verification by omitting the `.verify.secretRef` field. +To verify that the subject and the OIDC issuer present in the Fulcio certificate +you can specify `.spec.verify.cosignIdentityMatch`. It provides two fields: + +- `.issuerRegExp`, to sepcify a regexp that matches against the OIDC issuer. +- `.subjectRegExp`, to specify a regexp that matches against the identity in + the certificate. +Both values should follow the [Go regular expression syntax](https://golang.org/s/re2syntax). + Example of verifying HelmCharts signed by the [Cosign GitHub Action](https://github.com/sigstore/cosign-installer) with GitHub OIDC Token: @@ -325,6 +333,9 @@ spec: version: ">=6.1.6" verify: provider: cosign + cosignIdentityMatch: + subjectRegExp: "stefanprodan" + issuerRegExp: "^https://token.actions.githubusercontent.com$" ``` ```yaml diff --git a/docs/spec/v1beta2/ocirepositories.md b/docs/spec/v1beta2/ocirepositories.md index 2db354930..b23895211 100644 --- a/docs/spec/v1beta2/ocirepositories.md +++ b/docs/spec/v1beta2/ocirepositories.md @@ -506,6 +506,8 @@ signatures. The field offers two subfields: - `.provider`, to specify the verification provider. Only supports `cosign` at present. - `.secretRef.name`, to specify a reference to a Secret in the same namespace as the OCIRepository, containing the Cosign public keys of trusted authors. +- `.cosignIdentityMatch`, to specify the identity matching criteria if the + artifact was signed using Cosign keyless signing. ```yaml --- @@ -555,6 +557,14 @@ For publicly available OCI artifacts, which are signed using the [Cosign Keyless](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) procedure, you can enable the verification by omitting the `.verify.secretRef` field. +To verify that the subject and the OIDC issuer present in the Fulcio certificate +you can specify `.spec.verify.cosignIdentityMatch`. It provides two fields: + +- `.issuerRegExp`, to sepcify a regexp that matches against the OIDC issuer. +- `.subjectRegExp`, to specify a regexp that matches against the identity in + the certificate. +Both values should follow the [Go regular expression syntax](https://golang.org/s/re2syntax). + Example of verifying artifacts signed by the [Cosign GitHub Action](https://github.com/sigstore/cosign-installer) with GitHub OIDC Token: @@ -568,6 +578,9 @@ spec: url: oci://ghcr.io/stefanprodan/manifests/podinfo verify: provider: cosign + cosignIdentityMatch: + subjectRegExp: "stefanprodan" + issuerRegExp: "^https://token.actions.githubusercontent.com$" ``` The controller verifies the signatures using the Fulcio root CA and the Rekor