BRD — Distributed Exchange API Key (Securely Disposable Credentials)

[anhthii]

Status: Draft
Owner: Fystack / mpcium
Related: mpcium threshold MPC engine, pkg/mpc, NATS coordination

---

1. Background & Goal

Exchange API credentials (Binance, Bybit, etc.) are long-lived bearer secrets. Today they
are stored in one place (a config, a vault, a server process). Any single compromise of that
location leaks full trading authority.

Goal: make an exchange API key securely disposable — it exists in full exactly once
(at upload time), is split across the mpcium node set, and is never stored in any single
location thereafter. Signing of exchange requests is performed jointly by a threshold of
nodes, so no single party can sign alone and no full key can be recovered.

Success criteria

• The full secret appears in memory in exactly one place, exactly once (upload), then is wiped.
• No node, server, or operator can reconstruct the secret or sign a request alone.
• A threshold t-of-n of mpcium nodes can jointly produce a valid exchange signature.
• Output signatures are byte-identical to normal exchange signatures (exchange-agnostic).

---

2. Scope

In scope

• Distributing one exchange API secret across mpcium nodes at upload.
• Threshold joint signing of REST request payloads for supported exchanges.
• Secure disposal (memory wipe) of the full secret after distribution.

Out of scope (v1)

• Withdrawal-permission keys (recommend read/trade-only keys for v1).
• WebSocket session signing (REST first).
• Key rotation automation (manual re-upload acceptable for v1).

---

3. Functional Requirements

ID	Requirement
FR-1	Server exposes a one-time upload endpoint that accepts the exchange secret over an encrypted channel.
FR-2	On upload, the secret is split/shared to n mpcium nodes; the full secret is wiped from server memory immediately after distribution succeeds.
FR-3	No share, alone or below threshold, reveals the secret or enables signing.
FR-4	A sign request supplies the canonical request payload m; a quorum of t nodes jointly computes the signature without reconstructing the key.
FR-5	The signing engine returns the exchange-correct signature encoding (hex for HMAC, base64 for RSA/Ed25519).
FR-6	Payload canonicalization is exchange-specific and byte-exact (query ordering, body, timestamp, recvWindow).
FR-7	Signing completes within the exchange's freshness window (e.g. Binance recvWindow, default 5000 ms).
FR-8	All inter-node coordination is authenticated (reuse mpcium Ed25519 node identity).

4. Non-Functional Requirements

ID	Requirement
NFR-1	Single-appearance: full secret materializes once (upload) and is never persisted whole.
NFR-2	No single point of storage/trust for the secret at rest.
NFR-3	Threshold availability: any t-of-n online nodes can sign.
NFR-4	Active security: a malicious node cannot forge an incorrect signature or learn the key.
NFR-5	Latency budget: joint signing fits within exchange freshness window on the target network (LAN/WAN).
NFR-6	Auditability: every signing event is logged (who, when, which key, request hash) without logging the secret.

---

5. The Core Constraint — Signature Algorithm Decides Feasibility

Exchanges offer different signing algorithms per API key. The chosen algorithm dictates the
cryptographic approach and cost.

Exchange	HMAC-SHA256 (symmetric)	RSA (asymmetric)	Ed25519 (asymmetric)
Binance	✅ secret generated by exchange	✅ upload public key	✅ upload public key (exchange-recommended)
Bybit (v5)	✅ secret generated by exchange	✅ upload public key	⚠️ verify current support

• Symmetric (HMAC-SHA256): secret is exchange-generated, shown once → fits the "appears once,
  then disposed" model natively. Joint signing requires general-purpose boolean MPC over the
  SHA-256 circuit (no algebraic threshold scheme exists).
• Asymmetric (RSA / Ed25519): you generate the keypair and upload only the public key.
  Enables threshold signatures, and optionally DKG so the private key is never whole — even at
  creation — eliminating the disposal step entirely.

---

6. Available Options

Option A — Asymmetric + threshold signatures (preferred where supported)

• Ed25519 (Binance): reuse mpcium's existing threshold EdDSA (tss-lib). With DKG, the
  key is born as shares; nothing to dispose. Lowest cost, strongest model.
• RSA (Bybit, Binance): threshold RSA (dealer-split exponent, Shoup-style). tss-lib does
  not support this — new module required. Dealer is a one-time trust point at keygen.

Option B — Symmetric HMAC + boolean MPC (required when only HMAC is available)

• Dealer receives the exchange secret, secret-shares it, disposes the full key.
• Joint signing via MP-SPDZ boolean MPC over SHA-256 (separate subsystem, not tss-lib).
• Precompute key-dependent inner/outer states (S_i, S_o) once; per-signature cost ≈ 2–4
  SHA-256 compressions.
• Output is byte-identical to a normal HMAC signature; exchange cannot distinguish it.

Recommendation

• Default to Option A / Ed25519 (DKG) wherever the exchange allows — minimal new code, no
  dealer, no disposal risk.
• Use Option B (HMAC via MP-SPDZ) only for exchanges/keys that force symmetric auth.
• Threshold RSA only when an exchange forces asymmetric-RSA and Ed25519 is unavailable.

---

7. Key Algorithm / Technology Support Matrix

Approach	Crypto primitive	Engine	Dealer needed?	Full key ever exists?	Reuses mpcium/tss-lib?
Ed25519 threshold	Threshold EdDSA	tss-lib (existing)	No (DKG)	Never	✅ Yes
RSA threshold	Threshold RSA (Shoup)	New module	Yes (keygen)	At dealer keygen only	❌ No
HMAC-SHA256 threshold	Boolean MPC over SHA-256	MP-SPDZ (malicious-shamir-bin)	Yes (upload)	At upload only	❌ No (sibling subsystem)

---

8. High-Level Flow (HMAC / Option B)

1. UPLOAD (one time)
   client --TLS--> server : exchange secret K
   server: dealer-shares K to n mpcium nodes (persist S_i, S_o states)
   server: WIPE K from memory
2. SIGN (per request)
   caller -> mpcium: canonical payload m (public)
   quorum of t nodes -> MP-SPDZ joint compute HMAC-SHA256(K, m)
   mpcium -> caller: hex tag  ->  attach to exchange request

For Option A (Ed25519): replace step 1 with DKG (no secret upload), register the public key
with the exchange; step 2 is a threshold EdDSA session over m.

---

9. Risks & Open Questions

Risk / Question	Notes
Upload-moment exposure (HMAC/RSA-dealer)	Full key exists once at upload/keygen. Mitigate: air-gapped/HSM dealer, immediate wipe, audited code path. Eliminated entirely by Ed25519+DKG.
WAN latency vs. freshness window	SHA-256 boolean MPC has many rounds; must finish within recvWindow. Benchmark before commit.
Quorum availability	MP-SPDZ runs a fixed party set; "any t-of-n" needs a quorum/re-share design.
MP-SPDZ license	BSD-3 + commercial-use notification (not MIT/Apache); audit bundled deps (LGPL GMP). Run as separate process to keep license boundary clean.
Bybit Ed25519 support	Verify current algorithm options before choosing Option A for Bybit.
Payload canonicalization bugs	Byte-exact m required; mismatch = invalid signature. Per-exchange test vectors needed.
Withdrawal permissions	v1 restrict to read/trade keys; do not distribute withdrawal-capable keys until model is hardened.

---

10. Recommended v1 Plan

1. PoC: standalone MP-SPDZ malicious-shamir-bin computing HMAC-SHA256(K, m) with K
   shared, m public; validate against reference HMAC; measure LAN/WAN latency and licensing.
2. Parallel: prototype Ed25519 + DKG threshold signing against Binance testnet (reuses tss-lib).
3. Decide per exchange: Ed25519 where available, HMAC-via-MP-SPDZ otherwise.
4. Integrate chosen engine(s) as sibling subsystem(s) to mpcium, orchestrated over NATS, with
   per-exchange canonicalization + test vectors.