1"use strict";(globalThis.webpackChunkratify=globalThis.webpackChunkratify||[]).push([[3426],{28453(e,n,i){i.d(n,{R:()=>a,x:()=>o});var s=i(96540);const r={},t=s.createContext(r);function a(e){const n=s.useContext(t);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:a(e.components),s.createElement(t.Provider,{value:n},e.children)}},88063(e,n,i){i.r(n),i.d(n,{assets:()=>c,contentTitle:()=>o,default:()=>g,frontMatter:()=>a,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"external plugins/Verifier/cosign","title":"Cosign","description":"This README outlines how this validation framework can be used to verify signatures generated using cosign. The verifier is added as a plugin to the framework that uses cosign packages to invoke the verification of an image. Cosign verifier works with remote registry that can provide cosign related artifacts linked as specially formatted tag to the subject artifact. It also is compatible with OCI 1.1 supported Cosign which pushes the signature OCI Image as a referrer to the subject image. (Note: this is currently experimental for cosign) It works only with oras referrer store plugin that uses the OCI registry API to discover and fetch the artifacts.","source":"@site/versioned_docs/version-1.1/external plugins/Verifier/cosign.md","sourceDirName":"external plugins/Verifier","slug":"/external plugins/Verifier/cosign","permalink":"/docs/1.1/external plugins/Verifier/cosign","draft":false,"unlisted":false,"editUrl":"https://github.com/ratify-project/ratify-web/blob/main/versioned_docs/version-1.1/external plugins/Verifier/cosign.md","tags":[],"version":"1.1","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"External Plugins","permalink":"/docs/1.1/category/external-plugins"},"next":{"title":"SBOM Validation","permalink":"/docs/1.1/external plugins/Verifier/sbom"}}');var r=i(74848),t=i(28453);const a={},o="Cosign",c={},l=[{value:"Fallback in OCIRegistry store",id:"fallback-in-ociregistry-store",level:2},{value:"Key-pair based verification",id:"key-pair-based-verification",level:2},{value:"Configuration",id:"configuration",level:3},{value:"Kubernetes",id:"kubernetes",level:4},{value:"CLI",id:"cli",level:4},{value:"Usage",id:"usage",level:3},{value:"Keyless Verification",id:"keyless-verification",level:2},{value:"Configuration",id:"configuration-1",level:3},{value:"Kubernetes",id:"kubernetes-1",level:4},{value:"CLI",id:"cli-1",level:4},{value:"Usage",id:"usage-1",level:3}];function d(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",p:"p",pre:"pre",...(0,t.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"cosign",children:"Cosign"})}),"\n",(0,r.jsxs)(n.p,{children:["This README outlines how this validation framework can be used to verify signatures generated using ",(0,r.jsx)(n.a,{href:"https://github.com/sigstore/cosign/",children:"cosign"}),". The verifier is added as a plugin to the framework that uses ",(0,r.jsx)(n.a,{href:"https://github.com/sigstore/cosign/",children:"cosign"})," packages to invoke the verification of an image. Cosign verifier works with remote registry that can provide cosign related artifacts linked as specially formatted tag to the subject artifact. It also is compatible with OCI 1.1 supported Cosign which pushes the signature OCI Image as a referrer to the subject image. (Note: this is currently experimental for cosign) It works only with ",(0,r.jsx)(n.a,{href:"/docs/1.1/reference/crds/stores#oras",children:"oras"})," referrer store plugin that uses the OCI registry API to discover and fetch the artifacts."]}),"\n",(0,r.jsx)(n.h2,{id:"fallback-in-ociregistry-store",children:"Fallback in OCIRegistry store"}),"\n",(0,r.jsxs)(n.p,{children:["A configuration flag called ",(0,r.jsx)(n.code,{children:"cosignEnabled"})," is introduced to the plugin configuration. If this flag is enabled, the ",(0,r.jsx)(n.code,{children:"ListReferrers"})," API will attempt to query for the cosign signatures for a subject in addition to the references queried using ",(0,r.jsx)(n.code,{children:"referrers API"}),". If ",(0,r.jsx)(n.code,{children:"cosignEnabled"})," is ",(0,r.jsx)(n.code,{children:"false"}),", then only OCI 1.1 compatible Cosign signatures will be considered. All the cosign signatures are returned as the reference artifacts with the artifact type ",(0,r.jsx)(n.code,{children:"application/vnd.dev.cosign.artifact.sig.v1+json"})," This option will enable to verify cosign signatures against any registry including the ones that don't support the ",(0,r.jsx)(n.a,{href:"https://github.com/notaryproject",children:"notaryproject"}),"'s ",(0,r.jsx)(n.code,{children:"referrers"})," API."]}),"\n",(0,r.jsx)(n.h1,{id:"signing",children:"Signing"}),"\n",(0,r.jsxs)(n.p,{children:["Please refer cosign documentation on how to sign an image using cosign using ",(0,r.jsx)(n.a,{href:"https://docs.sigstore.dev/key_management/signing_with_self-managed_keys/",children:"key-pair based signatures"})," and ",(0,r.jsx)(n.a,{href:"https://docs.sigstore.dev/signing/quickstart/#keyless-signing-of-a-container",children:"keyless signatures"}),"."]}),"\n",(0,r.jsx)(n.h1,{id:"verification",children:"Verification"}),"\n",(0,r.jsx)(n.h2,{id:"key-pair-based-verification",children:"Key-pair based verification"}),"\n",(0,r.jsxs)(n.p,{children:["This section outlines how to use ",(0,r.jsx)(n.code,{children:"ratify"})," to verify the signatures signed using key pairs."]}),"\n",(0,r.jsxs)(n.p,{children:["Following is an example ",(0,r.jsx)(n.code,{children:"ratify"})," config with cosign verifier. Please note the ",(0,r.jsx)(n.code,{children:"key"})," refers to the public key generated by ",(0,r.jsx)(n.code,{children:"cosign generate-key-pair"})," command. It is used to verify the signature signed by cosign."]}),"\n",(0,r.jsx)(n.h3,{id:"configuration",children:"Configuration"}),"\n",(0,r.jsx)(n.h4,{id:"kubernetes",children:"Kubernetes"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"apiVersion: config.ratify.deislabs.io/v1beta1\nkind: Verifier\nmetadata:\n name: verifier-cosign\nspec:\n name: cosign\n artifactTypes: a
1pplication/vnd.dev.cosign.artifact.sig.v1+json\n parameters:\n key: /path/to/cosign.pub\n---\napiVersion: config.ratify.deislabs.io/v1beta1\nkind: Store\nmetadata:\n name: store-oras\nspec:\n name: oras\n parameters:\n cacheEnabled: true\n cosignEnabled: true\n ttl: 10\n"})}),"\n",(0,r.jsx)(n.h4,{id:"cli",children:"CLI"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'{\n "store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "cosignEnabled": true\n }\n ]\n },\n "policy": {\n "version": "1.0.0",\n "plugin": {\n "name": "configPolicy",\n "artifactVerificationPolicies": {\n "application/vnd.dev.cosign.artifact.sig.v1+json": "any"\n }\n }\n },\n "verifier": {\n "version": "1.0.0",\n "plugins": [\n {\n "name":"cosign",\n "artifactTypes": "application/vnd.dev.cosign.artifact.sig.v1+json",\n "key": "/path/to/cosign.pub"\n }\n ]\n }\n}\n'})}),"\n",(0,r.jsx)(n.h3,{id:"usage",children:"Usage"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'$ ratify verify --config ~/.ratify/config.json --subject myregistry.io/example/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4\n{\n "isSuccess": true,\n "verifierReports": [\n {\n "subject": "myregistry.io/example/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4",\n "isSuccess": true,\n "name": "cosign",\n "message": "cosign verification success. valid signatures found",\n "extensions": \n {\n "signatures": [\n {\n "bundleVerified": false,\n "isSuccess": true,\n "signatureDigest": "sha256:abc123"\n }\n ]\n },\n "artifactType": "application/vnd.dev.cosign.artifact.sig.v1+json"\n }\n ]\n}\n'})}),"\n",(0,r.jsx)(n.h2,{id:"keyless-verification",children:"Keyless Verification"}),"\n",(0,r.jsxs)(n.p,{children:["This section outlines how to use ",(0,r.jsx)(n.code,{children:"ratify"})," to verify the signatures signed using keyless signatures."]}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:"[!WARNING]\nCosign keyless verification may result in verification timeout due to Fulcio and Rekor server latencies"}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"configuration-1",children:"Configuration"}),"\n",(0,r.jsx)(n.h4,{id:"kubernetes-1",children:"Kubernetes"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-yaml",children:"apiVersion: config.ratify.deislabs.io/v1beta1\nkind: Verifier\nmetadata:\n name: verifier-cosign\nspec:\n name: cosign\n artifactTypes: application/vnd.dev.cosign.artifact.sig.v1+json\n parameters:\n rekorURL: https://rekor.sigstore.dev\n---\napiVersion: config.ratify.deislabs.io/v1beta1\nkind: Store\
1nmetadata:\n name: store-oras\nspec:\n name: oras\n parameters:\n cacheEnabled: true\n cosignEnabled: true\n ttl: 10\n"})}),"\n",(0,r.jsx)(n.h4,{id:"cli-1",children:"CLI"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'{\n "store": {\n "version": "1.0.0",\n "plugins": [\n {\n "name": "oras",\n "cosignEnabled": true\n }\n ]\n },\n "policy": {\n "version": "1.0.0",\n "plugin": {\n "name": "configPolicy",\n "artifactVerificationPolicies": {\n "application/vnd.dev.cosign.artifact.sig.v1+json": "any"\n }\n }\n },\n "verifier": {\n "version": "1.0.0",\n "plugins": [\n {\n "name":"cosign",\n "artifactTypes": "application/vnd.dev.cosign.artifact.sig.v1+json",\n "rekorURL": "https://rekor.sigstore.dev"\n }\n ]\n }\n}\n'})}),"\n",(0,r.jsxs)(n.p,{children:["Please note that the ",(0,r.jsx)(n.code,{children:"key"})," is not specified in the config. This is because the keyless verification uses ephemeral keys and certificates, which are signed automatically by the ",(0,r.jsx)(n.a,{href:"https://github.com/sigstore/fulcio",children:"fulcio"})," root CA. Signatures are stored in the ",(0,r.jsx)(n.a,{href:"https://github.com/sigstore/rekor",children:"Rekor"})," transparency log, which automatically provides an attestation as to when the signature was created."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"rekorURL"})," MUST be provided for keyless verification. Otherwise, signature validation will fail.\nIf using a custom Rekor transparency log instance, you can customize the Rekor URL using the ",(0,r.jsx)(n.code,{children:"rekorURL"})," field."]}),"\n",(0,r.jsx)(n.h3,{id:"usage-1",children:"Usage"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'$ ratify verify --config ~/.ratify/config.json --subject myregistry.io/example/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4\n{\n "isSuccess": true,\n "verifierReports": [\n {\n "subject": "myregistry.io/example/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4",\n "isSuccess": true,\n "name": "cosign",\n "message": "cosign verification success. valid signatures found",\n "extensions": \n {\n "signatures": [\n {\n "bundleVerified": true,\n "isSuccess": true,\n "signatureDigest": "sha256:abc123"\n }\n ]\n },\n "artifactType": "application/vnd.dev.cosign.artifact.sig.v1+json"\n }\n ]\n}\n'})})]})}function g(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.