docs: add docs for cosign identity matching

Signed-off-by: Sanskar Jaiswal <[email protected]>
fluxcd · Oct 9, 2023 · c16697c · c16697c
1 parent 9661617
commit c16697c
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 0 deletions.
diff --git a/docs/spec/v1beta2/helmcharts.md b/docs/spec/v1beta2/helmcharts.md
@@ -307,6 +307,15 @@ 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 the identity subject and the OIDC issuer present in the Fulcio
+certificate, you can specify a list of OIDC identity matchers using
+`.spec.verify.matchOIDCIdentity`. The matcher provides two fields:
+
+- `.issuer`, to specify a regexp that matches against the OIDC issuer.
+- `.subject`, to specify a regexp that matches against the subject 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 +334,9 @@ spec:
   version: ">=6.1.6"
   verify:
     provider: cosign
+    matchOIDCIdentity:
+      - issuer: "^https://token.actions.githubusercontent.com$"
+        subject: "^https://github.com/stefanprodan/podinfo.*$"
 ```
 
 ```yaml

diff --git a/docs/spec/v1beta2/ocirepositories.md b/docs/spec/v1beta2/ocirepositories.md
@@ -555,6 +555,15 @@ 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 the identity subject and the OIDC issuer present in the Fulcio
+certificate, you can specify a list of OIDC identity matchers using
+`.spec.verify.matchOIDCIdentity`. The matcher provides two fields:
+
+- `.issuer`, to specify a regexp that matches against the OIDC issuer.
+- `.subject`, to specify a regexp that matches against the subject 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 +577,9 @@ spec:
   url: oci://ghcr.io/stefanprodan/manifests/podinfo
   verify:
     provider: cosign
+    matchOIDCIdentity:
+      - issuer: "^https://token.actions.githubusercontent.com$"
+        subject: "^https://github.com/stefanprodan/podinfo.*$"
 ```
 
 The controller verifies the signatures using the Fulcio root CA and the Rekor