stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
2eafe98d44818e57a33ebe36d05d50f5f5737a7d
git.stella-ops.org/docs/modules/attestor/transparency.md
StellaOps Bot 2eafe98d44 save work
2025-12-19 07:28:23 +02:00

3.2 KiB
Raw Blame History

Transparency (DOCS-ATTEST-74-002)

Last updated: 2025-12-18

Purpose

StellaOps uses transparency logs (Sigstore Rekor v2 or equivalent) to provide tamper-evident, timestamped anchoring for DSSE bundles.

This document freezes the offline verification inputs used by Attestor in sealed/air-gapped operation and points to the canonical schema for rekor-receipt.json.

Offline Inputs (Air-Gap / Sealed Mode)

Baseline directory layout is defined in docs/product-advisories/14-Dec-2025 - Offline and Air-Gap Technical Reference.md:

/evidence/
  keys/
    tlog-root/             # pinned transparency log public key(s)
  tlog/
    checkpoint.sig         # signed tree head / checkpoint (note format)
    entries/               # *.jsonl entry pack (leaves + proofs)

Rekor Receipt (rekor-receipt.json)

The offline kit (or any offline DSSE evidence pack) may include a Rekor receipt alongside a DSSE statement.

  • Schema: docs/schemas/rekor-receipt.schema.json
  • Source: docs/product-advisories/14-Dec-2025 - Rekor Integration Technical Reference.md (Section 13.1) and docs/product-advisories/14-Dec-2025 - Offline and Air-Gap Technical Reference.md (Section 1.4)

Fields:

  • uuid: Rekor entry UUID.
  • logIndex: Rekor log index (integer, >= 0).
  • rootHash: expected Merkle tree root hash (lowercase hex, 32 bytes).
  • hashes: Merkle inclusion path hashes (lowercase hex, 32 bytes each; ordered as provided by Rekor).
  • checkpoint: either the signed checkpoint note text (UTF-8) or a relative path (e.g., checkpoint.sig, tlog/checkpoint.sig) resolved relative to the receipt file.

Checkpoint (checkpoint.sig)

/evidence/tlog/checkpoint.sig is the pinned signed tree head used for offline verification.

Contract:

  • Content is UTF-8 text using LF line endings.
  • The checkpoint MUST parse to the checkpoint body shape used by CheckpointSignatureVerifier (origin, tree size, base64 root hash, optional timestamp).
  • In offline verification, the checkpoint from receipts SHOULD match the pinned checkpoint (tree size + root hash).

Entry Pack (entries/*.jsonl)

/evidence/tlog/entries/*.jsonl is an optional-but-recommended offline mirror snapshot for bulk audit/replay.

Contract:

  • Files are NDJSON (one JSON object per line).
  • Each line uses the "Rekor Entry Structure" defined in docs/product-advisories/14-Dec-2025 - Rekor Integration Technical Reference.md (Section 4).
  • Deterministic ordering:
    • File names sort lexicographically (Ordinal).
    • Within each file, lines sort by rekor.logIndex ascending.

Offline Verification Rules (High Level)

  1. Load the pinned Rekor log public key from /evidence/keys/tlog-root/ (rotation is handled by shipping a new key file alongside the updated checkpoint snapshot).
  2. Verify the checkpoint signature (when configured) and extract tree size + root hash.
  3. For each rekor-receipt.json, verify:
    • inclusion proof path resolves to rootHash for the given leaf hash,
    • receipt checkpoint root matches the pinned checkpoint root (same tree head).
  4. Optionally, validate that each receipt's UUID/digest appears in the entry pack and that the recomputed Merkle root matches the pinned checkpoint.