Skip to content

Update cosign verify and system pages as well #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
steiza wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update cosign verify and system pages as well #420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1064910
Update cosign verify and system pages as well
steiza Mar 9, 2026
8063240
Remove FAQ content pointing a removed Gitsign Cosign verification page
steiza Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 0 additions & 83 deletions content/en/about/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,89 +59,6 @@ Yes! Sigstore currently has two GitHub Actions that make it easy to use Sigstore

You can learn more about using these GitHub Actions in our [Sigstore CI Quickstart]({{< relref "quickstart/quickstart-ci">}})

## Gitsign

### Why use Gitsign instead of the usual commit signing workflow?

A typical commit signing workflow requires developers to create special signing
keys that must be safely stored in the system that will sign the commits.
Additionally, verifying signatures requires access to the signer’s public key.
Distributing public keys while also attesting that they truly belong to a
certain identity can be very challenging. That’s where keyless signing comes in handy, allowing developers to
use their OpenID identities to sign commits and improve the overall trust of an
open source project.

### I signed my commit with Gitsign, but it shows up as “unverified” in my GitHub repository page. Why?

![Unverified signed commit](https://github.com/sigstore/gitsign/raw/main/images/unverified.png)

At the moment, GitHub doesn’t recognize Gitsign signatures as `verified` for two
reasons:

1. The Sigstore CA root is not a part of
[GitHub’s trust root](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#smime-commit-signature-verification).
2. Gitsign’s ephemeral keys are only valid for a short time, so using standard
x509 verification would consider the certificate invalid after expiration.
Verification needs to include validation via the [transparency log]({{< relref "logging/overview">}}) to
verify that the certificate was valid at the time it was used.

We hope to work closely with GitHub to get these types of signatures recognized
as verified in the near future.

You can find more information about GitHub’s commit signature verification in
their
[official docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).

### What data does Gitsign store?

Gitsign stores data in two places:

#### 1. Within the Git commit

The commit itself contains a signed digest of the user commit content (that is,
the author, committer, message, etc.) along with the code signing certificate.
This data is stored within the commit itself as part of your repository. Review
guidance on
[inspecting the Git commit signature]({{< relref "cosign/verifying/inspecting">}}) for
more details.

#### 2. Within the Rekor transparency log

To be able to verify signatures for ephemeral certs past their `Not After` time,
Gitsign records commits and the code signing certificates to
[Rekor]({{< relref "logging/overview">}}). This data is a
[HashedRekord](https://github.com/sigstore/rekor/blob/e375eb461cae524270889b57a249ff086bea6c05/types.md#hashed-rekord)
containing a SHA256 hash of the commit SHA, as well as the code signing
certificate. Review guidance on
[Verifying the Transparency Log](/logging/overview/#auditing-the-public-instance) for more
details.

By default, data is written to the
[public Rekor instance](/logging/overview/#auditing-the-public-instance). In
particular, users and organizations may be sensitive to the data contained
within code signing certificates returned by Fulcio, which may include user
emails or repository identifiers. Review
[OIDC Usage in Fulcio]({{< relref "certificate_authority/oidc-in-fulcio">}}) for more details regarding what
data is contained in the code signing certs. Alternately, you can learn how to
[Deploy a Rekor Server Manually](/logging/installation/#deploy-a-rekor-server-manually),
which would set up your own Rekor instance.

### Why does a browser window open for each commit in a rebase?

For Git, each commit in a rebase is considered a distinct signing operation so
by default an ephemeral key is generated for each commit. There are a
few options to help automating the authentication process:

* Setting the [`connectorID`](cosign/signing/gitsign/#configuration) value can be set to
automatically select the desired provider for Dex-backed OIDC providers
(including the public Sigstore instance at `oauth.sigstore.dev`). While this
still requires a browser window to open, this does not require an extra click
to select the provider.
* Starting in v0.2.0, Gitsign has experimental support for key caching to allow
users to reuse ephemeral keys for the lifetime of the Fulcio certificate. If
you are interested in learning more, check out the
[`gitsign-credential-cache` README](https://github.com/sigstore/gitsign/tree/main/cmd/gitsign-credential-cache).

## Rekor

### Is the transparency log monitored?
Expand Down
40 changes: 6 additions & 34 deletions content/en/cosign/system_config/registry_support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,41 +24,12 @@ Today, Cosign has been tested and works against the following registries:
* Alibaba Cloud Container Registry
* Quay.io and Project Quay Container Registry

We aim for wide registry support. To sign images in registries which do not yet fully support OCI media types, one may need to use `COSIGN_DOCKER_MEDIA_TYPES` to fall back to legacy equivalents. For example:

```shell
COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image
```

Please help test and file bugs if you see issues!
We aim for wide registry support. Please help test and file bugs if you see issues!
Instructions can be found in the [tracking issue](https://github.com/sigstore/cosign/issues/40).

## Rekor support
_Note: this is an experimental feature_

To publish signed artifacts to a Rekor transparency log and verify their existence in the log
set the `COSIGN_EXPERIMENTAL=1` environment variable.

```shell
COSIGN_EXPERIMENTAL=1 cosign sign --key cosign.key user/demo
COSIGN_EXPERIMENTAL=1 cosign verify --key cosign.pub user/demo
```

Cosign defaults to using the public instance of Rekor at [rekor.sigstore.dev](https://rekor.sigstore.dev).
To configure the Rekor server, use the -`rekor-url` flag

## Registry details

Cosign signatures are stored as separate objects in the OCI registry, with only a weak
reference back to the object they "sign".
This means this relationship is opaque to the registry, and signatures *will not* be deleted
or garbage-collected when the image is deleted.
Similarly, they **can** easily be copied from one environment to another, but this is not
automatic.

Multiple signatures are stored in a list which is unfortunately "racy" today.
To add a signature, clients orchestrate a "read-append-write" operation, so the last write
will win in the case of contention.
Cosign signatures are stored using the OCI 1.1 referrer specification.

## Specifying registry

Expand All @@ -68,7 +39,8 @@ To specify a different repo for signatures, you can set the `COSIGN_REPOSITORY`
This will replace the repo in the provided image:

```
export COSIGN_REPOSITORY=gcr.io/my-new-repo
gcr.io/user-vmtest2/demo -> gcr.io/my-new-repo/demo:sha256-DIGEST.sig
$ export COSIGN_REPOSITORY=gcr.io/my-new-repo
$ cosign sign gcr.io/user-vmtest2/demo
```
So the signature for `gcr.io/user-vmtest2/demo` will be stored in `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.

So the signature for `gcr.io/user-vmtest2/demo` will be stored in `gcr.io/my-new-repo/demo`.
Loading
Loading