Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/format-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -537,7 +537,8 @@ A bundle has one zip layout, so every reader sees the same entries; anything els
- each entry's data is exactly its stated size and matches its CRC-32.

`tracekit.bundle_v2` writes this layout (Python's `zipfile` writing a seekable file), and refuses a bundle past the
zip limits above, which no verifier would read.
zip limits above, which no verifier would read. It dates every entry 1980-01-01 00:00, so a bundle shows nothing of the
exporter's clock or time zone and the same files export to the same bytes; verifiers don't read entry dates.

**A run in parts** (from 1.4.0). A run whose records fit 64 MiB is one file, `runs/<id>.jsonl`, as before. A longer
one is written as `runs/<id>.part-0001.jsonl`, `runs/<id>.part-0002.jsonl`, ...: the run's file cut between records,
Expand Down
1 change: 1 addition & 0 deletions docs/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -559,6 +559,7 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees](
| `content_capture: full` stores content (redacted) in the log and in bundles. | Readable content is what the setting is for. | Protect such bundles as you would the data. | [privacy](privacy.md#content-capture-hashed-or-full) |
| Revealing a v2 record's salt lets anyone holding the content check that record's commitments. | That is how an auditor checks content; one salt opens one record. | Reveal only the records an audit needs. | [privacy](privacy.md#the-v2-signer) |
| A run-set bundle carries the tenant's registry salt, so it allows testing guessed run ids against that tenant's leaves. | The verifier needs the salt to check completeness. | Share run-set bundles only with that tenant's auditors. | [auditor guide](auditor-guide.md#3-get-the-bundles) |
| v2 bundles exported by earlier versions carry the exporter's local time in their zip entries, which next to the records' UTC times shows its time zone; v1 bundles still do. A v2 export now dates every entry 1980-01-01 00:00. | A zip entry is dated by the local clock unless its writer sets a date, and a bundle already written keeps its bytes. The v1 export isn't changed. | Re-export a v2 bundle to drop it: the records and proofs are the same. Use the v2 signer where the exporter's time zone is private. | [format v2](format-v2.md#9-bundle-layout) |
| With `serve_records: true` the metrics port serves every tenant's records (run ids, tool names, commitments). | The monitor reads every record. | Expose that port only to the monitor. | [monitor](monitor.md#run-it) |
| Witnesses learn when checkpoints happen and how many records exist; the public witness also learns each opted-in log's origin, so how often and how much each named log grows. | That is what they cosign, and it arrives when it is made. | Choose witnesses accordingly; for the public witness pick an `origin` that names nothing you want kept private, or don't opt in. | [privacy](privacy.md#what-hashes-and-metadata-still-leak), [public witness](privacy.md#what-leaves-the-machine) |

Expand Down
37 changes: 36 additions & 1 deletion tests/test_bundle_v2.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@
from unittest import mock


from factories import damage_crc, overinflate, rewrite_bundle, unverified_bundles
from factories import damage_crc, overinflate, patch_env, rewrite_bundle, unverified_bundles
from tracekit import cli, crypto
from tracekit.bundle_v2 import VERIFIER_MIN_VERSION, VERSIONS, bundle, export, needs, run_name
from tracekit.demo_server import tamper
from tracekit.format import checkpoint
from tracekit.format.canon import canonical
from tracekit.format.checkpoint import COSIGNATURE, ED25519, NoteError
Expand Down Expand Up @@ -965,6 +966,40 @@ def test_verifiers_need_only_the_standard_library(self):
self.assertIn(verdict, p.stdout)


@unittest.skipUnless(hasattr(time, "tzset"), "time.tzset is Unix only")
class TestEntryTimes(Case):
"""Every zip entry is dated 1980-01-01 00:00: the default date, the exporter's local clock, would show its time
zone against the records' UTC times."""

def setUp(self):
super().setUp()
self.addCleanup(time.tzset) # runs after patch_env puts TZ back
patch_env(self)

def zone(self, tz):
os.environ["TZ"] = tz
time.tzset()
self.assertEqual(time.localtime(0)[:6] == time.gmtime(0)[:6], tz == "UTC")

def test_every_entry_is_dated_1980_in_any_time_zone(self):
self.zone("JST-9")
_, out = self.honest()
with zipfile.ZipFile(out) as z:
self.assertEqual({i.date_time for i in z.infolist()}, {(1980, 1, 1, 0, 0, 0)})

def test_the_same_run_exports_to_the_same_bytes(self):
self.zone("UTC")
log, out = self.honest()
self.zone("JST-9")
again = os.path.join(self.d, "again.tkb")
export(log.store, "acme", "run-a", log.note(), again)
copy = os.path.join(self.d, "copy.tkb")
tamper(out, copy) # the demo's tampered copy, with no denied call to rewrite
for path in (again, copy):
with open(out, "rb") as a, open(path, "rb") as b:
self.assertEqual(a.read(), b.read(), path)


class TestRunParts(Case):
"""Format 1.4: a run whose records don't fit one file of a bundle is written in parts, split at records, which a
verifier reads in order as that one file; anything else about the parts fails `run parts` (format-v2.md §9)."""
Expand Down
11 changes: 10 additions & 1 deletion tracekit/bundle_v2.py
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ def export(storage, tenant, run_id, note, out_path, run_set=None, tenant_salt=No
with open(tmp, "wb") as f:
with zipfile.ZipFile(f, "w", zipfile.ZIP_DEFLATED) as z:
for n, b in files.items():
z.writestr(n, b)
z.writestr(zip_entry(n), b)
f.flush()
os.fsync(f.fileno())
os.replace(tmp, out_path)
Expand All @@ -249,6 +249,15 @@ def export(storage, tenant, run_id, note, out_path, run_set=None, tenant_salt=No
return {"bundle": out_path, **info}


def zip_entry(name):
"""A deflated zip entry dated 1980-01-01 00:00, the zip epoch: the default date, the exporter's local clock, would
show its time zone against the records' UTC times. A fixed date also makes an export of the same files the same
bytes."""
e = zipfile.ZipInfo(name, (1980, 1, 1, 0, 0, 0))
e.compress_type, e.external_attr = zipfile.ZIP_DEFLATED, 0o600 << 16 # as writestr(name, ...) sets them
return e


def bundle(storage, tenant, run_id, note, run_set=None, tenant_salt=None, with_runs=(), policy_dir=None, kept=None):
"""({name: bytes}, summary) of the bundle export() writes, manifest.json first, unzipped: what a verifier reads of
it. `kept`, for one run with no run-set, other runs or policy_dir (tracekit view, as a run grows): the summary's
Expand Down
4 changes: 2 additions & 2 deletions tracekit/demo_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
import zipfile

from tracekit import crypto
from tracekit.bundle_v2 import export
from tracekit.bundle_v2 import export, zip_entry
from tracekit.demo import say
from tracekit.deploy import files
from tracekit.format import checkpoint
Expand Down Expand Up @@ -104,7 +104,7 @@ def tamper(src, dst):
bundle[name] = bundle[name].replace(b'"decision":"deny"', b'"decision":"allow"', 1)
with zipfile.ZipFile(dst, "w") as z:
for n, v in bundle.items():
z.writestr(n, v)
z.writestr(zip_entry(n), v)


def report(rep, code, detail):
Expand Down
Loading