mirror of https://github.com/luxfi/corona.git synced 2026-09-24 00:25:54 +00:00

Files

T

zeekay fbe2bc5a88 submission: scaffold NIST MPTC v0.2 submission package mirroring Pulsar template

Adds the NIST MPTC Class N1 + N4 submission package for Corona (R-LWE
threshold signing). Pattern mirrors luxfi/pulsar (M-LWE byte-equal
FIPS 204 path), adapted HONESTLY to Corona's lighter proof tier:

- SUBMISSION.md / NIST-SUBMISSION.md — cover sheet + 1-page exec
  summary. Cite Boschini-Kaviani-Lai-Malavolta-Takahashi-Tibouchi
  ePrint 2024/1113 (IEEE S&P 2025) as the underlying construction.
  Construction-level N1 claim (no FIPS standard target for R-LWE
  threshold — Boschini et al. IS the spec). N4 = (A, bTilde)
  preserved across reshare within a key era.
- SPEC.md — standalone construction specification consolidating
  existing material (papers/lp-073-pulsar/, DESIGN.md). Full
  single-doc spec/corona.tex is roadmap v0.6.0.
- PATENTS.md — royalty-free patent grant + defensive termination.
  Claim scope EXCLUDES the published Boschini et al. construction;
  claims limited to Corona's production lifecycle additions
  (Pedersen DKG over R_q, proactive resharing, activation cert
  circuit-breaker, constant-time Pedersen slot equality, hash-suite
  injection).
- PROOF-CLAIMS.md — HONEST framing. Corona ships NO mechanized
  refinement (no EasyCrypt, no Lean, no Jasmin) — unlike Pulsar.
  Correctness reduces to code review + KAT cross-runtime byte-equality
  + academic construction analysis + per-path constant-time static
  audit. Mechanized refinement is roadmap v0.7.0.
- TRUSTED-COMPUTING-BASE.md — implementation TCB. Structurally
  simpler than Pulsar's; no EC/Lean/Jasmin tools in scope.
- DEPLOYMENT-RUNBOOK.md — operator-facing trust-model disclosure.
- LICENSING.md / CONTRIBUTING.md / SECURITY.md — standard NIST-MPTC
  artifacts.
- docs/mptc/ — submission-package docs subdir (kept separate from
  docs/ Next.js docs site):
  - evaluation.md, ietf-draft-skeleton.md, nist-mptc-category.md,
    patent-claims.md, design-decisions.md, family-architecture.md,
    threat-model.md
- scripts/{build,test,bench,gen_vectors,check-high-assurance,
  cut-submission}.sh — submission gates mirroring Pulsar's
  orchestrator pattern, adapted to Corona's reality (no EC/Lean/
  Jasmin checks because the artifacts do not exist).
- LLM.md + CHANGELOG.md — updated with submission scaffolding
  context and v0.5.0 entry. NO fabricated prior history; CHANGELOG
  v0.5.0 entry covers only the actual submission documentation.

DOES NOT FABRICATE: no CRYPTOGRAPHER-SIGN-OFF (Pulsar has one;
Corona's lighter proof tier does not yet warrant it — roadmap
v0.7.0+v0.8.0). No AXIOM-INVENTORY or FIPS-TRACEABILITY (Corona is
not anchored to a FIPS standard). No proof claims Corona does not
actually have.

Build/test verification: GOWORK=off go build ./... clean; sign/,
primitives/, hash/ unit tests pass; scripts/build.sh + scripts/
check-high-assurance.sh exit 0.

2026-05-18 23:10:13 -07:00

4.8 KiB

Raw Blame History

Contributing to Corona

What we accept

This repository is both a production Ring-LWE threshold signature library for Quasar consensus AND a NIST-MPTC-track submission package. Until the 2026-Nov-16 package submission, contributions that align with the MPTC submission are highest priority:

Specification clarity — text edits that disambiguate SPEC.md, DESIGN.md, and the LaTeX paper sections at papers/lp-073-pulsar/.
Reference implementation — sign/, threshold/, dkg2/, reshare/, primitives/, hash/. Boring, clear, no assembly, no clever abstractions. Match the spec section-by-section.
Test vectors — cmd/*_oracle*/. KAT-deterministic regeneration via scripts/regen-kats.sh; cross-runtime byte-equality with the C++ port at ~/work/luxcpp/crypto/corona/.
Constant-time analysis — CONSTANT-TIME-REVIEW.md. Show, don't claim. New entries must cite the relevant Go source line + the upstream primitive's CT guarantee.
Fuzz harness expansion — reshare/fuzz_*_test.go, dkg2/fuzz_round_test.go, threshold/fuzz_round_test.go.
Cryptanalysis of the Boschini et al. construction or Corona's production lifecycle additions — open an issue. We track external review explicitly.

What we don't accept

Until after the MPTC submission lands:

New protocol features beyond what the Boschini et al. construction
- Corona's production lifecycle layers specify.
Optimized implementations (AVX2, SIMD, hand-rolled assembly) in the reference. Optimized implementations belong in a separate build tag and require independent CT audit.
HSM integration patches in the reference (those belong in a separate consumer-side adapter library).
Production-deployment patches in the reference (use the consuming consensus layer for deployment-specific orchestration).
BLAKE3 hash-suite expansions — the NIST profile uses cSHAKE256 / KMAC256 / TupleHash256 exclusively (Corona-SHA3). The legacy Corona-BLAKE3 suite is retained for cross-port byte checks only; new BLAKE3 deltas should NOT land.
Patches that introduce Pulsar (M-LWE) types into Corona (R-LWE). The two libraries are independent with no shared types; keep them that way.

These reopen post-submission.

Process

Open an issue first. Discuss the change before implementing.
One concern per PR. Don't bundle spec edits with implementation changes. The MPTC review process treats them as separate artifacts.
CI must pass. Build, test, KAT regeneration, KAT cross-runtime verify, lattice-estimator (when wired) all green before merge.
Sign your commits. GPG-signed, real name in Signed-off-by. Patent-claim disclosures attach to commits.

Development setup

git clone https://github.com/luxfi/corona
cd corona
./scripts/build.sh
./scripts/test.sh
./scripts/gen_vectors.sh
./scripts/regen-kats.sh --verify    # cross-runtime byte-equality check

LaTeX spec build (paper sections):

cd papers/lp-073-pulsar/
pdflatex lp-073-pulsar-pedersen-dkg.tex
pdflatex lp-073-pulsar-resharing.tex

Coding standards (Go reference)

Go 1.26.3+ (per go.mod).
All logging via github.com/luxfi/log (consumer-supplied; the reference itself avoids logging on secret-touching paths). No log.Println, log.Fatalf, fmt.Printf in code that touches a secret.
All secret-byte comparison via crypto/subtle.ConstantTimeCompare or the local constTimePolyEqual helper in dkg2/dkg2.go:560.
All Gaussian sampling via lattigo's KeyedPRNG-backed ring.NewGaussianSampler. Direct math/rand is forbidden.
All hash usage via hash.HashSuite injection — never hardcode cSHAKE256 / KMAC256 / TupleHash256 outside hash/sp800_185.go. Direct golang.org/x/crypto/sha3 use is restricted to that file and the legacy hash/blake3.go for the cross-port byte-check suite only.
All Sign-path primitives take suite hash.HashSuite as their first argument (per F22 closure in CHANGELOG.md).
Errors carry context via fmt.Errorf("%w", err) not bare panics.
Patch-bump only — v0.4.1 → v0.4.2. Minor/major bumps require explicit approval (per CLAUDE.md rules).

Hash-suite discipline

Production: hash.Default() resolves to Corona-SHA3.
Legacy: hash.NewCoronaBLAKE3() for cross-port byte checks ONLY.
Adding a new suite requires updating hash/sp800_185.go with the customization strings, regenerating ALL KAT vectors, and updating the spec (SPEC.md §13).

License

By contributing, you agree your contribution is licensed under Apache-2.0 and grant the patent license described in the Apache 2.0 §3, AND the Corona-specific patent grant in PATENTS.md §3.

For NIST MPTC submission: contributions are subject to the patent-claim disclosures collected in docs/patent-claims.md.

4.8 KiB Raw Blame History