Specs

The specs/ directory contains the authoritative wire-format specifications cosign produces and verifies. They are versioned alongside the code so a given cosign release ↔ spec pairing is unambiguous.

Spec file	Subject
specs/SIGNATURE_SPEC.md	The on-the-wire format for cosign-style OCI image signatures (legacy and new bundle formats)
specs/BUNDLE_SPEC.md	The Sigstore protobuf bundle format (the v3 default)
specs/ATTESTATION_SPEC.md	DSSE-wrapped in-toto attestations attached to OCI artifacts
specs/COSIGN_PREDICATE_SPEC.md	The "cosign" in-toto predicate (the simple-signing claim wrapped as a predicate)
specs/COSIGN_VULN_ATTESTATION_SPEC.md	The cosign vulnerability-attestation predicate format
specs/SBOM_SPEC.md	Format guidance for SBOMs attached to images (legacy cosign attach sbom flow)

Why these are in-repo

External tools verify cosign-produced artifacts using nothing more than these specs and the relevant Sigstore trust roots. Keeping the specs versioned with the code:

1. Locks them to releases — cosign v3.x ships with whatever lives in specs/ at that tag.
2. Makes drift visible: a PR that changes the on-the-wire format must touch a spec file, which gets human review on the PR.
3. Lets cmd/conformance/ hand the same vectors to other Sigstore clients that consume these specs.

Headlines from each spec

SIGNATURE_SPEC.md

The deterministic-tag-and-layer scheme: for a digest sha256:<hex> of the signed image, signatures are stored as another OCI image at the tag sha256-<hex>.sig in the same (or COSIGN_REPOSITORY-overridden) repository. Each signature is a layer of the signature image; the base64 signature lives in the layer's dev.sigstore.cosign/signature annotation, the optional certificate, chain, and Rekor bundle in their own dev.sigstore.cosign/* annotations. The simple-signing JSON payload is the layer blob itself. The new bundle format puts a Sigstore protobuf bundle in the layer instead, with application/vnd.dev.sigstore.bundle.v0.3+json media type.

BUNDLE_SPEC.md

Wire format of the Sigstore protobuf bundle (dev.sigstore.bundle.v1 and v0.3). Defines the protobuf message shape (signature, certificate chain, Rekor inclusion proof, optional TSA timestamp), the choice between embedded and dereferenced messages, and the version negotiation rules. Cosign's serializer/deserializer is in pkg/cosign/bundle/protobundle.go.

ATTESTATION_SPEC.md

How DSSE-wrapped in-toto Statements are stored as attached OCI artifacts. Maps to cosign attest (write) and cosign verify-attestation (read).

COSIGN_PREDICATE_SPEC.md

A short spec for the "cosign" predicate type — essentially the simple-signing JSON wrapped as an in-toto predicate so it can flow through the attestation pipeline.

COSIGN_VULN_ATTESTATION_SPEC.md

The cosign-defined predicate type for vulnerability-scan attestations: scanner identity, scanned image digest, results, timestamps. Used by cosign attest --type vuln.

SBOM_SPEC.md

Documents the legacy "attach an SBOM as a sibling OCI artifact" flow. The current recommendation is to use SPDX/CycloneDX SBOMs as in-toto attestations instead (see cosign attest --type spdx|cyclonedx).

Cross-references

• Reading and writing the on-disk format: Library / OCI, Library / OCI / remote.
• Producing each format from the CLI: CLI / Signing.
• Verifying each format from the CLI: CLI / Verification.
• The protobuf bundle implementation in code: pkg/cosign/bundle/protobundle.go and pkg/cosign/bundle/sign.go.