sigstore · hayleycd · Feb 25, 2025 · Mar 2, 2025 · Mar 2, 2025 · Mar 3, 2025
diff --git a/content/en/about/api-stability.md b/content/en/about/api-stability.md
@@ -3,7 +3,7 @@
 category: About sigstore
 description: API stability levels and deprecation policy
 title: API Stability and Deprecation Policy
-weight: 5
+weight: 60
 ---
 
 This document covers API stability and the deprecation policy for Sigstore APIs and client libraries.
@@ -11,7 +11,7 @@
 ## What does this cover?

 The deprecation policy encompasses:
 * The client API for Fulcio
 * The client API for Rekor
 * Features provided by [cosign](https://github.com/sigstore/cosign)
 * The [sigstore/sigstore](https://github.com/sigstore/sigstore) client library
@@ -22,12 +22,12 @@
 There are three levels of stability and support:

 * Experimental
    * Features may be shipped with bugs
    * Feature is not yet recommended for production use
 * Beta
    * Features will be available for the next few releases
 * Generally Available
    * The feature will be available and supported 

 ## What is the deprecation policy at each level?


diff --git a/content/en/about/bundle.md b/content/en/about/bundle.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: Information about the Sigstore bundle format
 title: Sigstore Bundle Format
-weight: 4
+weight: 50
 ---
 
 Last updated January 14, 2025

diff --git a/content/en/about/contributing.md b/content/en/about/contributing.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: Intro text
 title: Contributing
-weight: 20
+weight: 80
 ---
 
 ## Contributing as a developer

diff --git a/content/en/about/doc_locations.md b/content/en/about/doc_locations.md
@@ -3,7 +3,7 @@ type: docs
 category: About Sigstore
 menuTitle: Documentation Locations
 title: Documentation Locations
-weight: 33
+weight: 100
 ---
 
 This document describes where to house new Sigstore documentation based on topic and intended audience.

diff --git a/content/en/about/faq.md b/content/en/about/faq.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 menuTitle: FAQs
 title: Frequently asked questions
-weight: 35
+weight: 110
 ---
 
 This FAQ is intended to go as in depth as possible for anyone using sigstore.

diff --git a/content/en/about/overview.md b/content/en/about/overview.md
@@ -4,7 +4,7 @@ category: About Sigstore
 description: Documentation for Sigstore
 home: true
 title: Overview
-weight: 1
+weight: 10
 ---
 
 ![Sigstore](sigstore-logo_horizontal-color.svg)
@@ -65,7 +65,7 @@ To use Sigstore, you must first install the client. Review the [Installation]({{
 - To learn how to work with blobs, see [sign a blob]({{< relref "cosign/signing/signing_with_blobs">}})
 - To learn how to work with containers, see [sign a container]({{< relref "cosign/signing/signing_with_containers">}})
 - To use Gitsign, see [Sign Git commits with Gitsign]({{< relref "cosign/signing/gitsign">}})
-- To learn about verification, see [verify entries with Cosign]({{< relref "cosign/verifying/verify">}})
+- To learn about verification, see [the importance of verification]({{< relref "about/the-importance-of-verification">}}) and [verify entries with Cosign]({{< relref "cosign/verifying/verify">}})
 - To learn about incorporating Sigstore into your CI System, see [our CI Quickstart]({{< relref "quickstart/quickstart-ci">}})
 
 ## Contributing

diff --git a/content/en/about/research.md b/content/en/about/research.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: ''
 title: Research
-weight: 40
+weight: 120
 ---
 
 ## Sigstore Research

diff --git a/content/en/about/security.md b/content/en/about/security.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: ''
 title: Security Model
-weight: 3
+weight: 30
 ---
 
 The Sigstore security model has a few key components, each aimed at establishing trust or proving identity. For a quick overview of the key services mentioned in this document, see [Tooling]({{< relref "about/tooling">}}).

diff --git a/content/en/about/support.md b/content/en/about/support.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: ''
 title: Get Help
-weight: 30
+weight: 90
 ---
 
 If you are not able to find the relevant information to solve your issue, you can still get help from the `sigstore` community!

diff --git a/content/en/about/the-importance-of-verification.md b/content/en/about/the-importance-of-verification.md
@@ -0,0 +1,29 @@
+---
+type: docs
+category: About sigstore
+menuTitle: The Importance of Verification
+title: The Importance of Verification
+weight: 70
+---
+
+## A note on verification
+
+As we learned in the [Sigstore overview](({{< relref "about/overview">}})), the Sigstore framework and tooling empowers software developers and consumers to securely sign and verify software artifacts (release files, container images, SBOMs, etc).
+
+With so many tools, and the ability to sign so many types of software artifacts, it could be easy to focus on the details of how to use the project and miss the large picture of what Sigstore is trying to accomplish. Our end goal is a secure software supply chain, but if projects are only using Sigstore to sign their artifacts and no one is verifying those signatures, we are no closer to our goal. A signature becomes valuable when it is checked.
+
+So we would like to implore you to not only make use of our [signing tools](({{< relref "cosign/signing/overview">}})) but of the [verification tools](({{< relref "cosign/verifying/verify">}})) as well.
+
+## For project maintainers
+
+Verfication requires the user of your software to have prior knowledge of the identity of the signer. To help users successfully verify your project we recommend that you publish the signature information in an easily discoverable place that can only be updated by trusted people. For example, the Python Software Foundation [publishes](https://www.python.org/downloads/metadata/sigstore/) a table that includes each signed CPython release, the release manager's email address, and the associated OIDC issuer.
+
+Your project README is an excellent place to let your users know that your project is signed with Sigstore and include a link to further signature information.
+
+## Verification Information
+
+Here are some quick links to further information on using Sigstore's verification tooling.
+
+* [Identity Verification Cheat Sheet](({{< relref "quickstart/verification-cheat-sheet">}}))
+* [Verifying with Cosign](({{< relref "cosign/verifying/verify">}}))
+* [Verifying using CI](({{< relref "quickstart/quickstart-ci">}}))
diff --git a/content/en/about/threat-model.md b/content/en/about/threat-model.md
@@ -3,7 +3,7 @@ type: docs
 category: About sigstore
 description: ''
 title: Threat Model
-weight: 3
+weight: 40
 ---
 
 ## Introduction

diff --git a/content/en/about/tooling.md b/content/en/about/tooling.md
@@ -9,7 +9,7 @@ features:
 - OpenID Connect (means of authentication)
 - policy-controller (enforcing container orchestration policy)
 title: Tooling
-weight: 2
+weight: 20
 ---
 
 Sigstore combines several different technologies that focus on automatic key management and transparency logs. They can be used independently or as one single process, and together they create a safer chain of custody tracing software back to the source.

diff --git a/content/en/cosign/verifying/verify.md b/content/en/cosign/verifying/verify.md
@@ -5,32 +5,34 @@ title: Verifying Signatures
 weight: 300
 ---
 
+When an artifact, blob, or container image is verified, the [full potential of Sigstore]({{< relref "about/the-importance-of-verification">}}) to secure the software supply chain is achieved.
+
 > **Note**: To verify a signed artifact or blob, first [install Cosign]({{< relref "cosign/system_config/installation">}}), then follow the instructions below.
 
 The general verification format with the `cosign verify` command is as follows.
 
 ```shell
-$ cosign verify [--key <key path>|<key url>|<kms uri>] <image uri>
+cosign verify [--key <key path>|<key url>|<kms uri>] <image uri>
 ```
+
 ## Keyless verification using OpenID Connect
 
 We'll use `user/demo` as our example image in the following commands and keyless signing where appropriate.
 
 For identity-based verification of a container image, use the following command:
 
-```
-$ cosign verify <image URI> [email protected]
-                            --certificate-oidc-issuer=https://accounts.example.com
-
+```shell
+cosign verify <image URI> [email protected]
+                          --certificate-oidc-issuer=https://accounts.example.com
 ```
 
 The oidc-issuer for Google is https://accounts.google.com, Microsoft is https://login.microsoftonline.com, GitHub is https://github.com/login/oauth, and GitLab is https://gitlab.com.
 
 The following example verifies the signature on file.txt from user [email protected] issued by [email protected]. It uses a provided bundle cosign.bundle that contains the certificate and signature.
 
-```
-$ cosign verify-blob <file> --bundle cosign.bundle [email protected]
-                              --certificate-oidc-issuer=https://accounts.example.com
+```shell
+cosign verify-blob <file> --bundle cosign.bundle [email protected]
+                          --certificate-oidc-issuer=https://accounts.example.com
 ```
 
 With container images, the signature and certificate are attached to the container.  For blobs, the signature and certificate can be stored in a bundle file that is created at the time of signing.  Either the bundle must be specified, or the individual signature and certificate must be specified.
@@ -56,27 +58,27 @@ verify any claims in the payload.
 You can pass more than one image to `cosign verify`.
 
 ```shell
-$ cosign verify user-0/demo-0 user-1/demo-1
+cosign verify user-0/demo-0 user-1/demo-1
 ```
 
 ## Local verifications
 
 Verify with an on-disk public key provided by the signer or other organization:
 
 ```shell
-$ cosign verify --key cosign.pub user/demo
+cosign verify --key cosign.pub user/demo
 ```
 
 Verify with an on-disk signed image from `cosign save`:
 
 ```shell
-$ cosign verify --key cosign.pub --local-image PATH/to/user/demo
+cosign verify --key cosign.pub --local-image PATH/to/user/demo
 ```
 
 Verify image with local certificate and local certificate chain:
 
 ```shell
-$ cosign verify --certificate cosign.crt --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
+cosign verify --certificate cosign.crt --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
 ```
 
 ## Verify image with user-provided trusted chain
@@ -88,14 +90,14 @@ Verify image with the provided certificate chain(s) and identity parameters (int
 certificates followed by the root CA certificate - use the `--certificate-chain` parameter:
 
 ```shell
-$ cosign verify --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
+cosign verify --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
 ```
 
 * with a certificate bundle PEM file containing several CA roots and (optionally)
 intermediate certificates, use the `--ca-roots` parameter together with `--ca-intermediates`:
 
 ```shell
-$ cosign verify --ca-roots ca-roots.pem --ca-intermediates ca-intermediates \
+cosign verify --ca-roots ca-roots.pem --ca-intermediates ca-intermediates \
   --certificate-oidc-issuer https://issuer.example.com \
   --certificate-identity [email protected] user/demo
 ```
@@ -105,27 +107,27 @@ The `--ca-roots` and `--ca-intermediates` flags are mutually exclusive with `--c
 ## Verify an image on the transparency log
 
 ```shell
-$ cosign verify user/demo
+cosign verify user/demo
 ```
 
 ## Verify attestation
 
 You can verify attestations on an image with `verify-attestation`.
 
 ```shell
-$ cosign verify-attestation user/demo
+cosign verify-attestation user/demo
 ```
 
 This will work with other flags, for example public key.
 
 ```shell
-$ cosign verify-attestation --key cosign.pub user/demo
+cosign verify-attestation --key cosign.pub user/demo
 ```
 
 You can also verify an attestation with the transparency log.
 
 ```shell
-$ cosign verify-attestation user/demo
+cosign verify-attestation user/demo
 ```
 
 ## Verify annotations
@@ -173,7 +175,7 @@ invalid or missing annotation in claim: map[sig:original]
 
 Each signature is printed to `stdout` in a JSON format:
 
-```
+```shell
 $ cosign download signature us-central1-docker.pkg.dev/user-vmtest2/test/taskrun
 {"Base64Signature":"Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg==","Payload":"eyJDcml0aWNhbCI6eyJJZGVudGl0eSI6eyJkb2NrZXItcmVmZXJlbmNlIjoiIn0sIkltYWdlIjp7IkRvY2tlci1tYW5pZmVzdC1kaWdlc3QiOiI4N2VmNjBmNTU4YmFkNzliZWVhNjQyNWEzYjI4OTg5ZjAxZGQ0MTcxNjQxNTBhYjNiYWFiOThkY2JmMDRkZWY4In0sIlR5cGUiOiIifSwiT3B0aW9uYWwiOm51bGx9"}
 ```
@@ -216,11 +218,12 @@ This may require special permissions, depending on the service.
 Another option is to use `cosign` to export the public key from the service, and you can use that to verify signatures:
 
 ```shell
-$ cosign public-key --key <some provider>://<some key> > kms.pub
-$ cosign verify --key kms.pub gcr.io/user-vmtest2/demo
+cosign public-key --key <some provider>://<some key> > kms.pub
+cosign verify --key kms.pub gcr.io/user-vmtest2/demo
 ```
 
 KMS:
+
 ```shell
 # Retrieve from Google Cloud KMS
 $ cosign public-key --key gcpkms://projects/someproject/locations/us-central1/keyRings/foo/cryptoKeys/bug/versions/1
@@ -236,6 +239,7 @@ MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgrKKtyws86/APoULh/zXk4LONqII
 AcxvLtLEgRjRI4TKnMAXtIGp8K4X4CTWPEXMqSYZZUa2I1YvHyLLY2bEzA==
 -----END PUBLIC KEY-----
 ```
+
 ## Custom Components
 
 For configuring Cosign to work with custom components, checkout the [Configuring Cosign with Custom Components]({{< relref "cosign/system_config/custom_components">}}) docs to find out how to achieve this.
@@ -244,7 +248,7 @@ For configuring Cosign to work with custom components, checkout the [Configuring
 
 You can override the public good instance CA using the environment variable `SIGSTORE_ROOT_FILE` by running the following.
 
-```
+```shell
 export SIGSTORE_ROOT_FILE="/home/jdoe/myrootCA.pem"
 ```
 
@@ -259,6 +263,7 @@ You can take existing signed material and make a new protobuf bundle with `cosig
 ### Verify a signature was added to the transparency log
 
 There are two options for verifying a Cosign signature was added to a transparency log:
+
 1. Check the log to make sure the entry exists in the log
 2. Use the `bundle` annotation on a Cosign signature to verify an element was added to the log without hitting the log
 
@@ -269,6 +274,7 @@ The SET can be verified with the logs public key and used to prove that an eleme
 For more details on how the `bundle` annotation is formatted, review the Cosign [spec](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md).
 
 To verify the `bundle` annotation, follow these steps:
+
 1. Marshal the `bundle` Payload into JSON
-1. Canonicalize the payload by following RFC 8785 rules
-1. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key
+2. Canonicalize the payload by following RFC 8785 rules
+3. Verify the canonicalized payload and signedEntryTimestamp against the transparency logs public key
diff --git a/content/en/quickstart/verification-cheat-sheet.md b/content/en/quickstart/verification-cheat-sheet.md
@@ -0,0 +1,35 @@
+---
+type: docs
+category: Quickstart
+description: Verification Cheat Sheet
+title: OIDC Verification Cheat Sheet
+weight: 20
+---
+
+## Identity Verification Cheat Sheet
+
+### Verying identity from OIDC issuers
+
+To verify a signature created with an OIDC issuer, you need to know the following:
+
+* `certificate-identity` : the email address associated with the signer for the given OIDC issuer
+* `certificate-oidc-issuer`: the url associated with the OIDC issuer
+
+| Issuer      | `certificate-oidc-issuer`                                              |
+| ----------- | ---------------------------------------------------------------------- |
+| GitHub      | [https://github.com/login/oauth](https://github.com/login/oauth)       |
+| GitLab      | [https://gitlab.com](https://gitlab.com)                               |
+| Google      | [https://accounts.google.com](https://accounts.google.com)             |
+| Microsoft   | [https://login.microsoftonline.com](https://login.microsoftonline.com) |
+
+If you are unsure of what values to expect, search the project's README, documentation, or website.
+
+#### Verifying a signature created by a workflow
+
+To verify a signature created by a workflow, you still need both the `certificate-identity` and the `certificate-oidc-issuer`, but they look a little different than when the signature is manually generated.
+
+For the case of a signature created with GitHub actions:
+
+| Issuer| `certificate-oidc-issuer`| `certificate-identity`|
+| ---- | --- | ----------- |
+| GitHub Actions | [https://token.actions.githubusercontent.com](https://token.actions.githubusercontent.com) | https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME |