> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Tamper-Evident Hash Chain
> Every evidence pack signs the previous one's manifest hash. Verify the chain years later with rbtk evidence verify-chain.
# Tamper-Evident Hash Chain
Every evidence pack a project produces is linked to its predecessor by hash and signed with a project-scoped Ed25519 key Roboticks holds in AWS KMS. The chain lets an auditor — or future-you, mid-recall — prove that no historical pack has been rewritten after the fact.
The chain is per-project. Each project has its own root pack and its own KMS key; chains do not cross projects.
## What is in the chain
Every pack's `evidence_pack.manifest.json` carries a `chain` block:
```json theme={null}
"chain": {
"parent_pack_id": "epak_01HF4ZN3…",
"parent_manifest_sha256": "7a02f1…",
"self_manifest_sha256": "9d11ba…",
"chain_index": 47
}
"signature": {
"algorithm": "ed25519",
"key_id": "arn:aws:kms:eu-west-1:…:key/abc-…",
"value": "MEQCIB…"
}
```
* `parent_manifest_sha256` is the previous pack's `self_manifest_sha256`. The root pack carries `parent_pack_id: null` and `parent_manifest_sha256: null`.
* `self_manifest_sha256` is the SHA-256 of this manifest with the `signature.value` field stripped (the signature cannot sign itself).
* `signature.value` is `Ed25519Sign(privKey, self_manifest_sha256)`.
A second pack mutated after the fact would have an `self_manifest_sha256` that no longer matches the `parent_manifest_sha256` carried by every successor. The mismatch is detectable without re-verifying signatures.
## Primitives
| Layer | Primitive |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Manifest hashing | SHA-256 |
| Signing | Ed25519 |
| Key storage | AWS KMS, project-scoped |
| Public key distribution | Published at `https://api.roboticks.io/api/v1/organizations/{org_slug}/projects/{project_slug}/evidence/public-key` and embedded in every pack's `README.md` |
Ed25519 was chosen for compactness (32-byte public keys, 64-byte signatures) and for the absence of nonce-reuse failure modes that plagued ECDSA deployments. SHA-256 is the obvious choice for ecosystem compatibility (every auditor tool already handles it).
## Verifying a single pack
```bash theme={null}
rbtk evidence verify epak_01HF5ZN3T0AAQ8X6BB1A8M2P3W
# … or, offline
rbtk evidence verify ./evidence-pack-v1.4.0.zip
```
The CLI:
1. Extracts the manifest, strips `signature.value`, computes the SHA-256.
2. Confirms it matches `self_manifest_sha256`.
3. Fetches the project's public key (or uses the embedded copy with `--offline`).
4. Verifies `Ed25519Verify(pubKey, signature.value, self_manifest_sha256)`.
5. Re-computes the SHA-256 of every artefact referenced in the manifest and compares to the declared hash.
A passing verification prints:
```
✓ Pack epak_01HF5ZN3T0AAQ8X6BB1A8M2P3W verified
Manifest SHA-256: 9d11ba…
Signature: valid (key arn:aws:kms:…)
Artefacts: 37 / 37 hashes match
Chain index: 47
```
## Verifying the full chain
```bash theme={null}
rbtk evidence verify-chain --project acme-robotics/firmware
```
The CLI walks the chain from the root pack to the latest, verifying each pack's signature and each `parent_manifest_sha256` link. Any failure stops the walk and prints the failing pack ID and reason.
For a project with 200 historical packs, expect a verify-chain to complete in \~30 seconds — most of the time is fetching manifests; signature math is microseconds per pack.
For long chains, parallelise the per-pack verification:
```bash theme={null}
rbtk evidence verify-chain --project acme-robotics/firmware --parallel 8
```
## What an auditor can prove
A passing `verify-chain` proves:
1. **Authenticity** — every pack was signed by the project's KMS key, meaning the Roboticks platform produced it.
2. **Integrity** — no artefact referenced in any pack has been altered since signing.
3. **Order** — packs are linked in their original generation order; no historical pack was retroactively inserted or removed.
4. **Non-repudiation** — the project owner cannot later disavow having signed a pack (the KMS key is logged and rotated audibly).
It does **not** prove:
* The underlying tests were correct.
* The requirements pinned were the right ones.
* The auditor's interpretation of the standard was correct.
The hash chain is an integrity primitive. The substance of the evidence is the substance of your engineering. See the [Disclaimer](/standards/disclaimer).
## Key rotation
Project KMS keys rotate annually as a matter of policy. Rotation does not invalidate historical signatures — old signatures continue to verify against the historical public key, which is retained in the chain manifest (`signature.key_id` records the exact key used at signing time).
Rotation is transparent to verification: the CLI fetches whichever historical public key the `key_id` resolves to.
## What if a pack is missing
A pack can become unreachable — accidentally deleted in S3, evicted by an aggressive retention policy, lost in a region outage. The chain itself is unbroken (the successor still references the missing pack's hash), but the missing pack cannot be re-verified.
`rbtk evidence verify-chain` flags missing packs as `MISSING` and continues. The chain remains usable for every pack that is present; the missing one is documented in the verification report as an unrecoverable gap. The recommended remediation is to regenerate the pack from the same release (Releases are pinned commit sets; regenerated packs hash differently, but you can demonstrate the regeneration matches the original by re-running the same tests).
## Compliance value
Many functional-safety regimes (IEC 61508, IEC 62061, EN ISO 13849, EU MR 2023/1230 technical-file rules) require evidence retention with integrity guarantees. The chain is what lets you tell a regulator, decades later, that the evidence in front of them is the evidence you produced at the time — not a post-hoc reconstruction.
**Roboticks is audit-readiness tooling, not a certified toolchain.** We assemble the evidence your notified body, certification body, or QA process ingests. We do not replace tool qualification (DO-178C, ISO 26262-8 TCL) and we do not issue conformity assessments. Verify the regulatory interpretations on this page against the standard text and your accredited assessor.