cosign

cosign supports using Key Management Service (KMS) providers to generate and sign keys. Supported native providers include:

• Hashicorp Vault
• AWS KMS
• GCP KMS
• Azure Key Vault

Additional providers, such as OVHcloud KMS, are available as external plugins.

To locate and retrieve Sigstore bundles associated with a specific image digest, follow these steps:

1. List referrers: Call the registry's referrers API using the image's digest: GET /v2/<repository>/referrers/<image-digest> Note: If this returns a 404 Not Found, fallback to the referrers tag scheme: GET /v2/<repository>/manifests/sha256-<image-digest>....
2. Identify the bundle: From the returned image index, find the manifest where the artifactType is application/vnd.dev.sigstore.bundle.v0.3+json.
3. Get the bundle manifest: Use the digest from the index to fetch the manifest: GET /v2/<repository>/manifests/<bundle-manifest-digest>
4. Download the bundle blob: Use the digest found in the first entry of the manifest's layers array to retrieve the actual JSON bundle: GET /v2/<repository>/blobs/uploads/?digest=<bundle-blob-digest>

To verify an image signed with keyless signing, you must provide the expected certificate identity and the OIDC issuer using the --certificate-identity and --certificate-oidc-issuer flags. You can also use regex versions of these flags: --certificate-identity-regexp and --certificate-oidc-issuer-regexp.

cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

Cosign supports creating and verifying in-toto attestations using the DSSE signing spec.

• Create/Sign: Use cosign attest --predicate <file> --key <key> <IMAGE_URI_DIGEST> to create an attestation from a local predicate file.
• Verify: Use cosign verify-attestation --key <public_key> <IMAGE_URI> to verify the attestation.

You can use cosign to publish generic artifacts (binaries, scripts, etc.) to an OCI registry as blobs.

1. Upload a blob: Use cosign upload blob -f <file> <URI> to upload a file. This returns the digest of the uploaded artifact.
2. Download a blob: Users can download the artifact using standard tools like curl or wget via the direct URL: https://<registry>/v2/<name>/blobs/sha256:<digest>.
3. Sign a blob: Use cosign sign --key <key> <digest_uri> to sign the uploaded artifact. Always use the digest to ensure you sign the correct content.

Use the cosign bundle create command to generate a Sigstore protobuf bundle by providing signed material. This bundle can be used to package signatures, certificates, and other metadata into a single file.

# create a bundle from a signature and certificate
cosign bundle create --artifact <path> --signature <sig> --certificate <cert> --out bundle.sigstore.json

# create a bundle from an attestation
cosign bundle create --artifact <path> --attestation <att> --out bundle.sigstore.json

Use the cosign piv-tool attestation command to manage and view hardware token attestations. This command allows you to retrieve attestation information from a specific slot on a hardware token, either in plain text or JSON format.

# print attestation information as text
cosign piv-tool attestation --slot 9c

# print attestation information as JSON
cosign piv-tool attestation --slot 9c --output json

When implementing or using tools to verify attestations for a container image, you must handle the relationship between the attestation's subject and the container image:

1. Mandatory Support: Implementations MUST support attestations that reference the entire container image.
2. Relationship Verification: Implementations MUST verify the relationship between the subject field (found in the Statement inside the Attestation) and the container image being verified.
3. Optional Support: While attestations MAY reference specific portions of an image, support for these partial-image relationship types is considered optional for implementations.

Use the cosign piv-tool generate-key command to generate a new signing key directly on a hardware token. By default, this generates a key in slot 9c with an always-touch policy.

# generate a key with default settings (slot 9c, always-touch policy)
cosign piv-tool generate-key

Since cosign signatures are stored as OCI artifacts, you can sign the signature itself to create a "counter-signature". This acts as an attestation to the original signature(s).

Workflow:

1. Sign the original artifact.
2. Give the resulting signature artifact a new tag (e.g., using crane).
3. Sign that new tag with a different key and a new annotation (e.g., -a sig=counter).