SimulatorAPI

README

SimulatorAPI Test Suite — README

(AI generated) This doc explains what the tests cover, how to run them, what files they write, and how to interpret results. It matches the setup with one CA (C1) and one logger (L1), where leaves used to compute the STH include RN and omit PoI (omitempty).

---

Overview

The test suite validates:

1. Server liveness (/healthz)
2. Certificates feed (/certificates) — dumped to disk
3. Periodic update bundle (/update) — STH/SRH + threshold signatures (BLS) + DCRV
4. PoI verification for every certificate against the STH root
5. CRV summary and mutation (/crv, /crv/revoke)
6. Period advancement (POST /advance) with refreshed artifacts & signatures

---

Prerequisites

• Go 1.21+
• Module deps resolved: go mod tidy
• Local files:
  • testconfig.json (CTng crypto config with DSS/TSS keys)
  • testsettings.json (CTng settings)
• The test and the server use github.com/herumi/bls-go-binary/bls (must match what def uses)

The tests load testconfig.json from the current working directory. Run go test from that directory or adjust the path in the helper.

---

Run the Server

go run .   -config testconfig.json   -settings testsettings.json   -listen :8080

Endpoints

Method	Path	Description
GET	/healthz	Plain liveness (“ok”).
GET	/certificates	Returns all certificates (struct includes RN + PoI).
GET	/crv	Summary: size, revoked_count, last_updated_at.
POST	/crv/revoke	Body: {"index": <uint>}; sets a bit in CRV; returns counts.
GET	/update	Bundle: period, sth, srh, dcrv, and threshold signature payloads.
POST	/advance	Advances period by 1; recomputes artifacts; returns fresh /update.

STH Leaf Encoding

• Included: SerialNumber, CAID, LoggerID, IssuedAt, Payload, RN
• Omitted: PoI (explicitly cleared before marshaling)

The test’s encodeLeafForSTH mirrors this exactly.

---

Tests

Test_EndToEnd_Update_Certs_CRV_PoI_ThresholdSigs_Advance

Flow:

1. GET /healthz
2. GET /certificates → dump to output_certificates.txt
3. GET /update → dump to output_update.txt
   • Rebuild def.ThresholdSig from payloads
   • Verify sthSig.Verify(json(STH), TSS_public_map) → must pass
   • Verify srhSig.Verify(json(SRH), TSS_public_map) → must pass
4. PoI verification for every cert (two-step):
   • Build leaf via encodeLeafForSTH(cert) (PoI cleared, RN included)
   • Try def.VerifyPOI(upd.STH, cert.PoI, leaf)
   • If that fails, try def.VerifyPOI2(upd.STH.Head, cert.PoI.Proof, leaf)
   • All certs must pass (either path)
5. GET /crv → dump to output_crv.txt
6. POST /crv/revoke (index=5) → dump to output_crv_revoke.txt
7. POST /advance → dump to output_advance.txt
   • Check period increased by 1
   • Re-verify STH/SRH threshold sigs

Run:

# server must already be running
go test -run Test_EndToEnd_Update_Certs_CRV_PoI_ThresholdSigs_Advance -v

Benchmark_VerifyPOIs (optional)

Micro-benchmark of PoI verification cost:

• Warm-up: fetch /certificates and /update
• Loop: verify each PoI with the same two-step approach
• Reports allocs/time

Run:

go test -bench=Benchmark_VerifyPOIs -benchtime=1x -cpu=1 -run ^$

---

Output Files

Generated in the working directory:

• output_certificates.txt — pretty JSON of cert array (includes RN + PoI for clients)
• output_update.txt — pretty JSON of period, sth, srh, dcrv, and threshold sig payloads
• output_crv.txt — CRV summary
• output_crv_revoke.txt — revocation response for index 5
• output_advance.txt — fresh update bundle after period advancement

---

Expected Results

• Threshold signatures (BLS): both STH and SRH payloads verify true using crypto.TSS_public_map
• PoIs: every certificate’s PoI passes verification (direct STH method or fallback root+proof)
• Advance period: period increments by exactly 1, and new STH/SRH signatures verify

---

Troubleshooting

• PoIs all fail

  • Ensure the leaf bytes match server encoding: RN present and correct, PoI omitted
  • Use the def.VerifyPOI / def.VerifyPOI2 helpers (consistent merkletree config)

• Threshold sigs fail

  • testconfig.json must match server keys
  • Ensure the test and def both use github.com/herumi/bls-go-binary/bls
  • Make sure you have at least crypto.Threshold monitor TSS keys

• HTTP errors (404/405)

  • Confirm /advance is registered:

    mux.HandleFunc("/advance", server.handleAdvancePeriod)
    

  • Restart the server after code changes

• Missing testconfig.json

  • Run go test from the directory containing the file, or adjust the path in the test

---

Determinism & Reproducibility

• IssuedAt uses current time at server startup, so roots change across runs.
• For stable roots:
  • Fix IssuedAt to a constant during generation, or
  • Cache generated certs and reuse them

---

Design Recap

• Topology: single CA (C1) and single logger (L1)
• RN: per-CA index [0..N-1] and included in leaf JSON
• PoI: attached to each cert for clients; omitted from leaf
• STH: Merkle root over JSON(cert with PoI cleared, RN present)
• SRH: Head = SHA256(CRV) || SHA256(Compress(CRV))
• Threshold signatures: BLS over JSON of STH/SRH, verified against aggregated monitor public keys

---

If you change what fields are serialized into STH leaves, update encodeLeafForSTH accordingly so tests remain aligned with the server.