Image signing and verification scenarios

Cosign offers a flexible architecture that integrates with a wide variety of cryptographic workflows. The examples on this page represent the most common image signing scenarios used within Mirantis Secure Registry (MSR).

Because Cosign supports many alternative signing methods, see the official Cosign documentation for a complete list of deployment scenarios and advanced configurations.

Sign with a self-managed key pair

This is the standard approach for managing your own cryptographic keys. You generate a private/public key pair locally, use the private key to sign the image, and use the public key to verify it. For more information, see the Sigstore documentation on self-managed keys.

Run the following command to generate a cosign.key (private key) and cosign.pub (public key). You are prompted to enter a password to protect the private key:
```
$ cosign generate-key-pair
```
Authenticate your container client to MSR, then use your private key to sign the target image tag. Cosign automatically pushes the signature artifact to your MSR repository:
```
$ cosign sign --key cosign.key \
    msr.example.com/marketing/nginx:v1
```

Verify the integrity and origin of the image using your public key:

$ cosign verify --key cosign.pub \
    msr.example.com/marketing/nginx:v1

Sign in an air-gapped environment

Cosign can operate in secure, offline, or air-gapped data centers because it does not depend on public internet services — such as the Fulcio or Rekor transparency logs — to function.

Before you begin, verify the following prerequisites:

The client machine running the Cosign CLI must have direct network access to the MSR instance.
If MSR uses a self-signed CA, the client machine must trust the MSR CA certificate in its OS trust store, or you must configure the registry under insecure-registries in the Docker daemon.json file.
Public transparency log uploads must be explicitly bypassed because there is no internet access to reach them.

Note

In an air-gapped environment, use the --tlog-upload=false flag with all Cosign commands to prevent contact with public transparency logs.

Sign and push the image:

$ cosign sign --key cosign.key --tlog-upload=false \
    msr.example.com/secure-zone/alpine:latest

Verify the signature:

$ cosign verify --key cosign.pub --tlog-upload=false \
    msr.example.com/secure-zone/alpine:latest

Sign images with attestations

Attestations allow you to append authenticated metadata — such as vulnerability scan reports, build provenance, or SBOMs — directly to your container images. This metadata can later be evaluated by admission controllers.

For information on enforcing attestation policies at deployment time, see the Sigstore Policy Controller documentation.

Attest a predicate file containing build details or scan results to the image. Adjust --type to match your attestation predicate format:

$ cosign attest --key cosign.key --type custom \
    --predicate scan-results.json \
    msr.example.com/dev/api-service:v2

Verify that the attestation exists and is valid:

$ cosign verify-attestation --key cosign.pub --type custom \
    msr.example.com/dev/api-service:v2

For more information on attestations, see the Cosign attestation overview.

Sign with identity-based signing using OIDC

Cosign supports keyless signing, which eliminates the challenges of managing long-lived cryptographic keys. Instead of generating and storing permanent keys, Cosign uses an OpenID Connect (OIDC) identity token from a trusted identity provider (IdP) to obtain a short-lived signing certificate from Sigstore’s Fulcio Certificate Authority.

This scenario is commonly used in automated CI/CD environments such as GitHub Actions, GitLab CI, or cloud providers using workload identity.

Sign and push the image. When you run this command interactively, Cosign opens a browser to complete an OIDC authorization challenge. In CI/CD pipelines, Cosign automatically detects the ambient OIDC token from the runner environment, or you can supply one explicitly using the --identity-token flag:
```
$ cosign sign --identity-token="$OIDC_TOKEN" msr.example.com/production/web-app:v1
```

Verify the signature. Because no public key file exists, specify the expected OIDC provider issuer URL and the identity embedded in the certificate, such as a developer’s email address or a CI/CD workflow path:

$ cosign verify \
    --certificate-identity="deploy-service@company.iam.gserviceaccount.com" \
    --certificate-oidc-issuer="https://accounts.google.com" \
    msr.example.com/production/web-app:v1

For more information on keyless signing, see the Cosign keyless signing overview.