fieldwitness/docs/evidence-guide.md

Evidence Guide

Audience: Journalists, investigators, and legal teams who need to create, export, and verify evidence packages from SooSeF.

Prerequisites: A running SooSeF instance with at least one attested image or file. Familiarity with basic CLI commands.

---

Overview

SooSeF provides three mechanisms for preserving and sharing evidence outside a running instance: evidence packages (for handing specific files to third parties), cold archives (full-state preservation for 10+ year horizons), and selective disclosure (proving specific records without revealing the rest of the chain). All three include standalone verification scripts that require no SooSeF installation.

---

Evidence Packages

An evidence package is a self-contained ZIP that bundles everything needed for independent verification of specific attested images or files.

What is inside an evidence package

File	Purpose
images/	Original image files
manifest.json	Attestation records, chain data, and image hashes
public_key.pem	Signer's Ed25519 public key
verify.py	Standalone verification script
README.txt	Human-readable instructions

Creating an evidence package

# Package specific images with their attestation records
$ soosef evidence export photo1.jpg photo2.jpg --output evidence_package.zip

# Filter by investigation tag
$ soosef evidence export photo1.jpg --investigation "case-2026-001" \
    --output evidence_case001.zip

When to create evidence packages

• Before handing evidence to a legal team or court
• When sharing with a partner organization that does not run SooSeF
• Before crossing a hostile checkpoint (create the package, send it to a trusted party, then activate the killswitch if needed)
• When an investigation is complete and files must be archived independently

Verifying an evidence package

The recipient does not need SooSeF. They need only Python 3.11+ and the cryptography pip package:

$ python3 -m venv verify-env
$ source verify-env/bin/activate
$ pip install cryptography
$ cd evidence_package/
$ python verify.py

The verification script checks:

1. Image SHA-256 hashes match the attestation records in manifest.json
2. Chain hash linkage is unbroken (each record's prev_hash matches the previous record)
3. Ed25519 signatures are valid (if public_key.pem is included)

---

Cold Archives

A cold archive is a full snapshot of the entire SooSeF evidence store, designed for long-term preservation aligned with OAIS (ISO 14721). It is self-describing and includes everything needed to verify the evidence decades later, even if SooSeF no longer exists.

What is inside a cold archive

File	Purpose
chain/chain.bin	Raw append-only hash chain binary
chain/state.cbor	Chain state checkpoint
chain/anchors/	External timestamp anchor files (RFC 3161 tokens, manual anchors)
attestations/log.bin	Full verisoo attestation log
attestations/index/	LMDB index files
keys/public.pem	Signer's Ed25519 public key
keys/bundle.enc	Encrypted key bundle (optional, password-protected)
keys/trusted/	Trusted collaborator public keys
manifest.json	Archive metadata and SHA-256 integrity hashes
verify.py	Standalone verification script
ALGORITHMS.txt	Cryptographic algorithm documentation
README.txt	Human-readable description

Creating a cold archive

# Full archive without encrypted key bundle
$ soosef archive export --output archive_20260401.zip

# Include encrypted key bundle (will prompt for passphrase)
$ soosef archive export --include-keys --output archive_20260401.zip

Warning: If you include the encrypted key bundle, store the passphrase separately from the archive media. Write it on paper and keep it in a different physical location.

When to create cold archives

• At regular intervals (weekly or monthly) as part of your backup strategy
• Before key rotation (locks the existing chain state in the archive)
• Before traveling with the device
• Before anticipated risk events (raids, border crossings, legal proceedings)
• When archiving a completed investigation

Restoring from a cold archive

On a fresh SooSeF instance:

$ soosef init
$ soosef archive import archive_20260401.zip

Long-term archival best practices

1. Store archives on at least two separate physical media (USB drives, optical discs)
2. Keep one copy offsite (safe deposit box, trusted third party in a different jurisdiction)
3. Include the encrypted key bundle in the archive with a strong passphrase
4. Periodically verify archive integrity: unzip and run python verify.py
5. The ALGORITHMS.txt file documents every algorithm and parameter used, so a verifier can be written from scratch even if SooSeF no longer exists

The ALGORITHMS.txt file

This file documents every cryptographic algorithm, parameter, and format used:

• Signing: Ed25519 (RFC 8032) -- 32-byte public keys, 64-byte signatures
• Hashing: SHA-256 for content and chain linkage; pHash and dHash for perceptual image matching
• Encryption (key bundle): AES-256-GCM with Argon2id key derivation (time_cost=4, memory_cost=256MB, parallelism=4)
• Chain format: Append-only binary log with uint32 BE length prefixes and CBOR (RFC 8949) records
• Attestation log: Verisoo binary log format

---

Selective Disclosure

Selective disclosure produces a verifiable proof for specific chain records while keeping others redacted. Designed for legal discovery, court orders, and FOIA responses.

How it works

Selected records are included in full (content hash, content type, signature, metadata, signer public key). Non-selected records appear only as their record hash and chain index. The complete hash chain is included so a third party can verify that the disclosed records are part of an unbroken chain without seeing the contents of other records.

Creating a selective disclosure

# Disclose records at chain indices 5, 12, and 47
$ soosef chain disclose --indices 5,12,47 --output disclosure.json

Disclosure output format

{
  "proof_version": "1",
  "chain_state": {
    "chain_id": "a1b2c3...",
    "head_index": 100,
    "record_count": 101
  },
  "selected_records": [
    {
      "chain_index": 5,
      "content_hash": "...",
      "content_type": "verisoo/attestation-v1",
      "prev_hash": "...",
      "record_hash": "...",
      "signer_pubkey": "...",
      "signature": "...",
      "claimed_ts": 1711900000000000,
      "metadata": {}
    }
  ],
  "redacted_count": 98,
  "hash_chain": [
    {"chain_index": 0, "record_hash": "...", "prev_hash": "..."},
    {"chain_index": 1, "record_hash": "...", "prev_hash": "..."}
  ]
}

Verifying a selective disclosure

A third party can verify:

1. Chain linkage: each entry in hash_chain has a prev_hash that matches the record_hash of the previous entry
2. Selected record integrity: each selected record's record_hash matches its position in the hash chain
3. Signature validity: each selected record's Ed25519 signature is valid for its canonical byte representation

When to use selective disclosure vs. evidence packages

Need	Use
Hand specific images to a lawyer	Evidence package
Respond to a court order for specific records	Selective disclosure
Full-state backup for long-term preservation	Cold archive
Share attestations with a partner organization	Federation bundle

---

Chain Anchoring for Evidence

External timestamp anchoring strengthens evidence by proving that the chain existed before a given time. A single anchor for the chain head implicitly timestamps every record that preceded it, because the chain is append-only with hash linkage.

RFC 3161 automated anchoring

If the device has internet access (even temporarily):

$ soosef chain anchor --tsa https://freetsa.org/tsr

This sends the chain head digest to a Timestamping Authority, receives a signed timestamp token, and saves both as a JSON file under ~/.soosef/chain/anchors/. The TSA token is a cryptographically signed proof from a third party that the hash existed at the stated time. This is legally stronger than a self-asserted timestamp.

Manual anchoring (airgapped)

Without --tsa:

$ soosef chain anchor

This prints a compact text block. Publish it to any external witness:

• Tweet or public social media post (timestamped by the platform)
• Email to a trusted third party (timestamped by the mail server)
• Newspaper classified advertisement
• Bitcoin OP_RETURN transaction
• Notarized document

Anchoring strategy for legal proceedings

1. Anchor the chain before disclosing evidence to any party
2. Anchor at regular intervals (daily or weekly) to establish a timeline
3. Anchor before and after major events in an investigation
4. Anchor before key rotation
5. Save anchor files alongside key backups on separate physical media

---

Legal Discovery Workflow

For responding to a court order, subpoena, or legal discovery request:

1. Selective disclosure (soosef chain disclose) when the request specifies particular records and you must not reveal the full chain
2. Evidence package when the request requires original images with verification capability
3. Cold archive when full preservation is required (e.g., an entire investigation)

All three formats include standalone verification scripts so the receiving party does not need SooSeF installed. The verification scripts require only Python 3.11+ and the cryptography pip package.

Note: Consult with legal counsel before producing evidence from SooSeF. The selective disclosure mechanism is designed to support legal privilege and proportionality, but its application depends on your jurisdiction and the specific legal context.