Skip to content

VERIFY-ARTIFACTS.md

Latest commit

 

History

History
114 lines (87 loc) · 4.39 KB

VERIFY-ARTIFACTS.md

File metadata and controls

114 lines (87 loc) · 4.39 KB
Raw

Verify TunaOS artifacts

TunaOS uses Sigstore Cosign to sign its OCI images with a keyless identity from GitHub Actions. The project keeps no key or password for signatures, and you need none to verify. Verification checks both the artifact digest and the identity of the protected workflow that built it.

Install Cosign

Use Cosign 3.0.6 or newer. Follow the upstream installation instructions and verify the Cosign binary before using it.

Verify an OCI image

Always resolve and verify an immutable digest, even when you start from a friendly tag:

image=ghcr.io/tuna-os/yellowfin:gnome
digest=$(skopeo inspect "docker://${image}" | jq -r .Digest)
ref="ghcr.io/tuna-os/yellowfin@${digest}"

cosign verify "${ref}" \
  --certificate-identity \
    "https://github.com/tuna-os/tunaOS/.github/workflows/reusable-build-image.yml@refs/heads/main" \
  --certificate-oidc-issuer \
    "https://token.actions.githubusercontent.com"

The command must exit successfully. Do not replace the identity or issuer with an unrestricted regular expression.

Verify the SPDX SBOM attestation

Each published platform image has a signed attestation in SPDX JSON format. A different workflow signs it: attest-sbom.yml runs after the build run finishes. So an outage of Sigstore gives that run its own result, not the result of the nightly (#2282). The identity below shows this. The identity of the image signature, above, stays the same.

cosign verify-attestation "${ref}" \
  --type spdxjson \
  --certificate-identity \
    "https://github.com/tuna-os/tunaOS/.github/workflows/attest-sbom.yml@refs/heads/main" \
  --certificate-oidc-issuer \
    "https://token.actions.githubusercontent.com"

Cosign prints the verified in-toto statement. Its subject[].digest.sha256 must match the digest in ref. The predicate contains the SPDX document for that platform image. The document lists the packages and the relationships between them. It does not list the files of each package. With the files, the document was 38-123 MB, and Rekor refuses a request over 24 MiB (#2697).

Trust boundary

The accepted identity is intentionally narrow:

  • repository: tuna-os/tunaOS;
  • workflow: .github/workflows/reusable-build-image.yml for image signatures, .github/workflows/attest-sbom.yml for SBOM attestations;
  • ref: protected refs/heads/main;
  • OIDC issuer: GitHub Actions.

A signature from a fork, pull-request ref, another repository, another workflow, or another identity provider does not satisfy this policy.

Verify an ISO

Every published ISO has two adjacent files:

  • <name>.iso.sha256 — the SHA-256 checksum manifest, and the signed payload;
  • <name>.iso.sigstore.json — the keyless bundle from Cosign v3, over that checksum file, not over the ISO.

Download all three files into the same directory, then run:

cosign verify-blob tunaos-example.iso.sha256 \
  --bundle tunaos-example.iso.sigstore.json \
  --certificate-identity \
    "https://github.com/tuna-os/tunaOS/.github/workflows/reusable-build-artifacts.yml@refs/heads/main" \
  --certificate-oidc-issuer \
    "https://token.actions.githubusercontent.com"

expected="$(awk 'NR == 1 {print $1}' tunaos-example.iso.sha256)"
printf '%s  %s\n' "$expected" tunaos-example.iso | sha256sum --check --strict -

The order matters. The bundle signs the checksum file, not the ISO. The first command proves the checksum came from our pipeline. The second checks the downloaded ISO against the digest in that file. It does not use the ISO filename. Rollback snapshots keep signed checksum bytes and use checksum-based ISO names.

The payload is the checksum because cosign sign-blob reads what it signs into memory, and an ISO above roughly 7 GiB exhausts the runner. Fedora, Debian and Arch publish signatures over checksums for the same reason.

publish-iso-groups.yml produces scheduled combined/deduplicated media directly. For those ISOs, use this exact identity instead:

https://github.com/tuna-os/tunaOS/.github/workflows/publish-iso-groups.yml@refs/heads/main

The workflow for reusable artifacts signs only after the ISO passes its QEMU boot gate; the grouped workflow uses the same order. The workflow then uploads the verified ISO, checksum, and bundle together. A failure of the signature step or of local verification prevents publication.