# Magnetar --- TEE integration specification This document is the canonical design + integration story for Magnetar's TEE-attested production surface. It is the load-bearing prose for the `strict-PQ` chain profile at deployment time. > **Decomplecting discipline.** The TEE integration is the > SIBLING package at `luxfi/threshold/protocols/slhdsa-tee` --- > NOT a new field on the magnetar primitive. Magnetar stays the > hash-tree arithmetic; slhdsa-tee composes the trust root + > attestation + HSM + approval flow. The two compose by function > composition, not by inheritance. --- ## 1. Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Caller (RPC / EVM precompile) │ └──────────────┬──────────────────────────────────┬───────────┘ │ Sign / Sign_Ctx │ Sign_TEE / Combine_TEE │ (legacy-compat) │ (strict-PQ) ▼ ▼ ┌───────────────────────┐ ┌──────────────────────────────────┐ │ magnetar.ValidatorSign│ │ slhdsa-tee.Signer.Sign │ │ (per-validator) │ │ • approval.ApproveIntent │ └───────────────────────┘ │ • gate.Issue (nonce+epoch) │ │ • gate.Release (attest+RIM) │ ┌───────────────────────┐ │ • hsm.Provider.GetKey │ │ magnetar.Combine │ │ • magnetar.Sign (inside TEE) │ │ (strict-atom Combine)│ │ • zeroize on return │ │ (THBS-SE public) │ └──────────────────────────────────┘ └───────────────────────┘ │ ▼ ┌──────────────────────────────────┐ │ slhdsa-tee.CombinerPool.Combine │ │ • snapshot members under RLock │ │ • freshness gate (RotationWindow)│ │ • drive each member's Sign │ │ • byte-equality across quorum │ │ • refuse divergence │ └──────────────────────────────────┘ │ ▼ ┌──────────────────────────────────┐ │ cc/attest/{sev,tdx,nras}.go │ │ • SEV-SNP: PRODUCTION │ │ • TDX: STUB (#222 stage 2) │ │ • NRAS: STUB (#222 stage 3) │ └──────────────────────────────────┘ ``` --- ## 2. Component contracts ### 2.1 Magnetar (this repo) - **Lane**: FIPS 205 hash-tree arithmetic (FORS, WOTS+, XMSS, hypertree). Pure functions. - **Inputs (sign path)**: `Params, *PrivateKey, msg, ctx, randomized, rng`. - **Output**: `Signature` (FIPS 205 wire bytes). - **No knowledge of**: TEE, HSM, approval, gate, attestation. Pure crypto. ### 2.2 slhdsa-tee.Signer (sibling, `luxfi/threshold/protocols/slhdsa-tee`) - **Lane**: institutional-custody composition. The full attested-release flow that ends in a magnetar.Sign call. - **Inputs**: `Envelope (attestation, RIM, hardware, TEEPub), jobID, msg, signCtx`. - **Output**: `(wireBytes, *SignReceipt, error)`. - **Composes**: `kms.ReleaseGate + hsm.Provider + approval.ApprovalProvider + Config`. - **Does NOT compose** magnetar itself --- the Signer holds an `hsm.Provider` reference and unwraps the master seed inside the TEE, then calls `magnetar.KeyFromSeed + magnetar.Sign` on the unwrapped seed. ### 2.3 slhdsa-tee.CombinerPool (sibling) - **Lane**: t-of-n attested-combiner agreement. The strict-PQ Sign surface. - **Inputs**: `map[memberName]*Envelope, jobID, msg, signCtx`. - **Output**: `(wireBytes, []*SignReceipt, error)` --- one consolidated wire signature byte-equal across the quorum, plus per-member audit signatures. - **Composes**: N `*slhdsa-tee.Signer` instances (one per attested host) + freshness state (`LastIssuedAt` per member). - **Refusal sentinels**: `ErrMagnetarNoTEEAttestation`, `ErrMagnetarStaleAttestation`, `ErrMagnetarInsufficientQuorum`, `ErrMagnetarSignatureDivergence`. ### 2.4 cc/attest (sibling, `luxfi/mpc/cc/attest`) - **Lane**: vendor evidence chain validation. Maps from vendor-framed quote bytes to `VerifiedReport` (Vendor + IssuedAt + ReportData). - **Status**: SEV-SNP PRODUCTION; TDX + NRAS STUB. ### 2.5 hsm.Provider (sibling, `luxfi/mpc/pkg/hsm`) - **Lane**: at-rest seed wrap. Implementations include file (dev), AWS KMS, Azure Key Vault, GCP Cloud KMS. - **Inputs**: `keyID, ctx`. - **Output**: wrapped (or AEAD-sealed) bytes. ### 2.6 kms.ReleaseGate (sibling, `luxfi/mpc/pkg/kms`) - **Lane**: fresh-nonce + policy-bound release decision. - **Issue**: returns `(nonce, epoch)` for a job; must be presented in the subsequent Release call. - **Release**: takes `ReleaseRequest{JobID, Epoch, Nonce, Attestation, Ctx}` and returns a `SealedSessionKey` if policy + attestation pass. ### 2.7 approval.ApprovalProvider (sibling, `luxfi/mpc/pkg/approval`) - **Lane**: out-of-band human / programmatic approval of a sign intent. Used when `Config.ApprovalRequired = true`. - **Inputs**: `SignIntent` (jobID, msg, env-bound). - **Output**: `ApprovalSignature`. --- ## 3. Profile gate (one function, one place) The profile gate is **the only** decomplecting point between the permissionless and strict-PQ paths. The function is `magnetarRefuseUnderStrictPQ` at `luxfi/threshold/pkg/thresholdd/magnetar.go:242`. It mirrors: - `RefuseUnderStrictPQ` at `luxfi/precompile/contract/strict_pq.go` (precompile-side gate consulted at the top of every classical precompile's `Run`). - `RefuseUnderStrictPQ` at `luxfi/threshold/pkg/thresholdd/ profile.go` (per-request chain-ID resolver gate for HTTP 503 mapping). ### Discipline 1. **ONE function**. No duplication across schemes (every PQ primitive that has a strict-PQ-only path consults its own gate function with this exact shape). 2. **ONE place**. Called at the top of `Sign` and `Sign_Ctx` --- the permissionless paths. Never called from `Sign_TEE` / `Combine_TEE` (which are the strict-PQ-permitted paths). 3. **ONE canonical refusal sentinel**. `slhdsatee.ErrMagnetarNoTEEAttestation` with wire identifier `ERR_MAGNETAR_NO_TEE_ATTESTATION`. ### Cascade on chain profile flip Operators rotating a chain into strict-PQ MUST follow: 1. Flip the chain profile in `luxfi/node` ChainConfig. 2. Flip the magnetar dispatcher's profile via `magnetarScheme.SetChainSecurityProfile(ProfileStrictPQ)`. 3. Wire a `CombinerPool` via `SetCombinerPool` with at least `Threshold` attested members already provisioned. Until all three steps complete, the dispatcher fail-closes: `Sign` / `Sign_Ctx` refuse; `Combine_TEE` refuses with `errMagnetarPoolUnwired`. No silent fallback. --- ## 4. Production deployment matrix | Chain profile | Sign primitive | TEE substrate | KnownIssuers map | |---|---|---|---| | `legacy-compat` (default) | per-validator standalone | none | --- | | `legacy-compat` (THBS-SE) | public combiner | none | --- | | `legacy-compat` (custody opt-in) | `Combine_TEE` (1-of-1) | SEV-SNP | `{"amd.sev.snp": {}}` | | `strict-PQ` (production today) | `Combine_TEE` (t-of-n) | SEV-SNP | `{"amd.sev.snp": {}}` | | `strict-PQ` (post-#222 stage 2) | `Combine_TEE` (t-of-n) | SEV-SNP + TDX | `{"amd.sev.snp": {}, "intel.tdx": {}}` | | `strict-PQ` (post-#222 stage 3) | `Combine_TEE` (t-of-n) | + NVIDIA NRAS | `{"amd.sev.snp": {}, "intel.tdx": {}, "nvidia.nras.v1": {}}` | ### 4.1 NVIDIA Confidential Computing (H100 / H200 / B200) integration When `luxfi/mpc/cc/attest/nras.go` ships its production chain validator (NVIDIA Remote Attestation Service, `nvtrust` SDK integration), the operator's CombinerPool config adds `"nvidia.nras.v1": {}` to KnownIssuers. Each attested member's slhdsa-tee.Signer runs inside a NVIDIA Confidential Compute VM on H100/H200/B200. The CC VM's measurement (firmware + UEFI + VBS + TEE workload) is chain-validated against NRAS's JWKS. No magnetar-side code change. For the **deployment-time** Apple SE / Apple Silicon story, see the v1.4 work item `MAGNETAR-APPLE-SE-HSM-V14` --- the Apple SE is layered BELOW the attestation as the `hsm.Provider`, not as a substitute for the attestation chain. --- ## 5. Wire compatibility The TEE integration is **completely opaque to verifiers**. Any party holding the canonical MAGG-framed group public key validates a TEE-emitted signature via stock `magnetar.VerifyBytes(gkBytes, msg, sigBytes)` --- no special casing, no TEE-aware verifier, no extra round-trips. This is the load-bearing property: the TEE substrate provides custody discipline, NOT verification discipline. The on-chain verifier (the EVM precompile at slot `0x012207`) does NOT know or care whether the signature came from: - a per-validator standalone keypair on a commodity host, - a public combiner on a commodity host running THBS-SE, - a 1-of-1 attested-host TEE, - a t-of-n attested-combiner pool spanning SEV-SNP + TDX + NRAS. All four paths emit byte-identical FIPS 205 wire bytes. --- ## 6. Stub Go integration code (operator-side reference) The following is a minimal operator-side reference for wiring a `strict-PQ` chain into the magnetar dispatcher with NVIDIA Confidential Compute. It is NOT in this repo (the TEE primitives live at `luxfi/threshold/protocols/slhdsa-tee`); reproduced here for the spec's completeness. ```go package main import ( "context" "time" "github.com/luxfi/mpc/cc/attest" "github.com/luxfi/mpc/pkg/approval" "github.com/luxfi/mpc/pkg/hsm" "github.com/luxfi/mpc/pkg/kms" magnetar "github.com/luxfi/magnetar/ref/go/pkg/magnetar" slhdsatee "github.com/luxfi/threshold/protocols/slhdsa-tee" "github.com/luxfi/threshold/pkg/thresholdd" ) // configureMagnetarStrictPQ wires a strict-PQ Magnetar dispatcher // with a 2-of-3 attested-combiner pool across AMD SEV-SNP + // NVIDIA NRAS. Called once at operator boot. func configureMagnetarStrictPQ( ctx context.Context, dispatcher *thresholdd.MagnetarScheme, gate kms.ReleaseGate, hsmP hsm.Provider, approver approval.ApprovalProvider, ) error { // 1. Flip the dispatcher into strict-PQ. From this point on, // Sign / Sign_Ctx refuse with ErrMagnetarNoTEEAttestation. // Only Sign_TEE / Combine_TEE can produce signatures. dispatcher.SetChainSecurityProfile(slhdsatee.ProfileStrictPQ) // 2. Build the attested-combiner pool. KnownIssuers includes // both AMD SEV-SNP (production today) AND NVIDIA NRAS // (post-#222 stage 3). pool, err := slhdsatee.NewCombinerPool(slhdsatee.CombinerPoolConfig{ Threshold: 2, // 2-of-3, no single-host quorum RotationWindow: 60 * time.Second, // 60 blocks of slack KnownIssuers: map[string]struct{}{ "amd.sev.snp": {}, "nvidia.nras.v1": {}, // assumes cc/attest/nras.go has shipped }, }) if err != nil { return err } // 3. Register the three attested signers. Each signer has its // own wrapped seed in its own HSM key slot; the pool drives // each member's full slhdsa-tee.Signer.Sign machinery. for _, m := range []struct { name string keyID string mode magnetar.Mode }{ {name: "us-east-1a-snp-01", keyID: "magnetar/east/snp01", mode: magnetar.ModeM192s}, {name: "us-west-2b-snp-02", keyID: "magnetar/west/snp02", mode: magnetar.ModeM192s}, {name: "eu-central-1a-nras-01", keyID: "magnetar/eu/nras01", mode: magnetar.ModeM192s}, } { signer, err := slhdsatee.New(gate, hsmP, approver, slhdsatee.Config{ Mode: m.mode, WrappedSeedKeyID: m.keyID, ApprovalRequired: true, // require human sign-off per call ApproverID: "operator@example.com", RequireSEV: false, // accept any KnownIssuer RequireTDX: false, RequireNRAS: false, }) if err != nil { return err } if _, err := pool.AddMember(m.name, signer); err != nil { return err } } // 4. Wire the pool into the dispatcher. From this point on, // Combine_TEE drives the pool; Sign_TEE drives a single // attested host. dispatcher.SetCombinerPool(pool) // 5. Initial attestation tick. Production deployments would // re-attest every block (~1s); the 60s RotationWindow // absorbs ~60 blocks of control-plane latency before any // sign would refuse. for _, name := range []string{ "us-east-1a-snp-01", "us-west-2b-snp-02", "eu-central-1a-nras-01", } { // The operator's control-plane captures fresh attestation // evidence from the named TEE and submits it. env := captureFreshAttestation(name) // operator-side hook if err := pool.Attest(ctx, name, env); err != nil { return err } } return nil } // captureFreshAttestation is the operator's control-plane hook. // For SEV-SNP: capture SNP_GUEST_REQUEST quote via the in-VM agent. // For TDX: capture TDREPORT via the in-VM agent. // For NRAS: capture NRAS-JWT via nvidia-attest agent + NRAS API. // Each returns an *slhdsatee.Envelope wrapping the vendor quote. func captureFreshAttestation(name string) *slhdsatee.Envelope { // ... vendor-specific quote capture ... return &slhdsatee.Envelope{ Kind: attest.Kind{ Vendor: "amd.sev.snp", // or "nvidia.nras.v1" Format: "snp.v1", // or "nras.jwt.v1" }, EvidenceBytes: nil, // populate from quote RIM: [32]byte{}, // operator-asserted RIM digest Hardware: [32]byte{}, // hardware fingerprint TEEPub: [32]byte{}, // X25519 TEE pubkey } } ``` The above is the operator-side wiring; the magnetar reference package itself stays pure. --- ## 7. Verification end-to-end Pinned by `magnetar_tee_gate_test.go` in `luxfi/threshold/pkg/thresholdd/`: - `TestMagnetarCombine_StrictPQProfile_RequiresTEE` --- strict-PQ refuses `Sign` and `Sign_Ctx`; permits `Combine_TEE` only when pool is wired; profile flip is reversible + idempotent. - `TestMagnetarCombine_AttestationVerified_AllowsSign` --- end-to-end pool drive against committed AMD Milan SEV-SNP fixture; output verifies under `magnetar.VerifyBytes` (no caller awareness of the pool's existence). - `TestMagnetarCombine_StaleAttestation_RejectsSign` --- members outside rotation window refused; partial re-attestation recovers. - `TestMagnetarCombine_TwoOfThreeAttestedCombiners_MatchSig` --- 2-of-3 quorum surfaces signature; 1-of-3 stops. - `TestMagnetarCombine_SignatureDivergence_HardRefusal` --- pool refuses byte-divergent quorum output (no silent winner-picking). All five tests pass under `-race` against the committed Milan SEV-SNP fixture (`pkg/thresholdd/testdata/sev_snp_attestation_milan.bin`, `sev_snp_vcek_milan.cer`) replayed via `dispatchKDSReplay()`. --- **Document metadata** - Name: `TEE-INTEGRATION.md` - Date: 2026-06-03 - Pin: Magnetar v1.2 + slhdsa-tee at commit b1c0..f8d