panchajanya1999/sage-estimator repository overview

⁠sage-estimator

REST API for precise ML-KEM (FIPS 203) and ML-DSA / Dilithium (FIPS 204) security estimation using malb/lattice-estimator⁠ and leaky-LWE-Estimator⁠.

Computes BKZ blocksize, classical/quantum security bits, and decryption failure rates for any ML-KEM parameter set, plus dual MLWE + MSIS security for ML-DSA. Supports side-channel leakage analysis via the leaky-LWE-Estimator (Ducas et al.).

⁠Quick Start

docker run -d --name sage-estimator \
  -p 5123:5000 \
  --memory 12g \
  -e CACHE_PATH=/data/cache.json \
  -v sage-data:/data \
  panchajanya1999/sage-estimator:latest

The service precomputes 6 standard parameter sets on startup (~10-15 min):

• ML-KEM: 512, 768, 1024 (FIPS 203)
• ML-DSA: 44, 65, 87 (FIPS 204)

# Health check
curl http://localhost:5123/health

# Check prewarm progress (ready when count = 6)
curl http://localhost:5123/cache

⁠Endpoints

⁠ML-KEM (FIPS 203)

⁠ML-DSA / Dilithium (FIPS 204)

⁠Common

⁠ML-KEM Usage

# Submit estimate — cached result (200)
curl -X POST http://localhost:5123/estimate \
  -H 'Content-Type: application/json' \
  -d '{"k": 3, "eta1": 2, "eta2": 2, "du": 10, "dv": 4}'
# {"beta": 624, "classical": 182, ..., "source": "cached", "status": "done"}

# Submit estimate — new computation (202)
curl -X POST http://localhost:5123/estimate \
  -H 'Content-Type: application/json' \
  -d '{"k": 3, "eta1": 3, "eta2": 3, "du": 10, "dv": 4}'
# {"status": "computing", "job_id": "23cc08da", "elapsed": 0}

# Poll until done
curl http://localhost:5123/status/23cc08da
# {"beta": 660, "classical": 192, ..., "status": "done"}

⁠ML-KEM Parameters

⁠Standard FIPS 203 Sets

⁠ML-DSA (Dilithium) Usage

The Dilithium endpoint computes both MLWE (key recovery) and MSIS (forgery resistance) security. Overall security = min(MLWE, MSIS).

# Submit ML-DSA-44 estimate
curl -X POST http://localhost:5123/estimate_dilithium \
  -H 'Content-Type: application/json' \
  -d '{"k": 4, "l": 4, "eta": 2, "gamma1": 131072, "gamma2": 95232}'
# {"status": "computing", "job_id": "e9a2863a", "elapsed": 0}

# Poll until done (~60-90 seconds)
curl http://localhost:5123/status/e9a2863a
# {"mlwe_beta": 424, "mlwe_classical": 123, "mlwe_quantum": 112,
#  "msis_beta": 1128, "msis_classical": 329, "msis_quantum": 298,
#  "status": "done", "source": "computed"}

⁠ML-DSA Parameters

⁠Standard FIPS 204 Sets

⁠MSIS Estimation Notes

The MSIS estimate uses the native SIS.estimate() from the lattice-estimator with L2 (Euclidean) norm. The infinity norm estimator has an upstream gmpy2/SageMath compatibility bug. L2 norm provides a conservative upper bound — the real forgery problem (SelfTargetMSIS) is harder still.

⁠Side-Channel Leakage Analysis (Leaky-LWE)

Both /estimate and /estimate_dilithium accept optional leakage parameters to model security degradation when an attacker has partial knowledge of the secret key via side channels (DPA, power analysis, etc.).

Uses the leaky-LWE-Estimator⁠ by Ducas et al. (DBDD_predict_diag variant for large dimensions).

⁠Leakage Parameters

⁠Leakage Models

• Perfect ("perfect"): Exact bits leaked (e.g., DPA revealed N coordinates of the secret key). Models the worst-case scenario.
• Approximate ("approx"): Noisy measurements (e.g., N power traces with variance sigma^2). Models realistic side-channel attacks.

⁠ML-KEM Leakage Example

# ML-KEM-512 with 50 perfectly leaked coordinates
curl -X POST http://localhost:5123/estimate \
  -H 'Content-Type: application/json' \
  -d '{"k": 2, "eta1": 3, "eta2": 2, "du": 10, "dv": 4,
       "leak_type": "perfect", "leak_amount": 50}'

# Response includes standard + leaky fields:
# {"beta": 382, "classical": 111, ...,
#  "leaky_beta": 347.8, "leaky_classical": 101,
#  "leaky_quantum": 92, "security_loss_bits": 13, ...}

50 leaked coordinates (~10% of ML-KEM-512's 512-dimensional secret) drops classical security from ~111 to ~101 bits — a 13-bit loss.

⁠ML-DSA Leakage Example

# ML-DSA-44 with 50 perfectly leaked coordinates
curl -X POST http://localhost:5123/estimate_dilithium \
  -H 'Content-Type: application/json' \
  -d '{"k": 4, "l": 4, "eta": 2, "gamma1": 131072, "gamma2": 95232,
       "leak_type": "perfect", "leak_amount": 50}'

# Response: mlwe_leaky_beta=335.8, mlwe_leaky_classical=98, security_loss=6 bits
# MSIS fields unchanged — forgery resistance is unaffected by key leakage

For ML-DSA, leakage analysis applies to MLWE only — MSIS (forgery resistance) is unaffected by key leakage.

⁠Leaky Response Fields

⁠Attack Strategies

The estimator runs 6 attacks against the Module-LWE instance:

⁠Caching

Results are cached in-memory and persisted to Docker volumes:

Each unique parameter set is computed once (~30s-2min for ML-KEM, ~60-90s for ML-DSA, leaky adds ~2-5min via SageMath), then served instantly from cache.

⁠Memory Requirements

⁠Architecture

• Base image: condaforge/miniforge3 with SageMath via conda-forge
• Platforms: linux/arm64, linux/amd64
• Async API: Non-blocking submit + poll pattern for long computations
• Deduplication: Duplicate submissions for the same params reuse existing jobs
• Leaky-LWE: SageMath subprocess via DBDD_predict_diag (Ducas et al.)

⁠References

• NIST FIPS 203⁠ — ML-KEM specification
• NIST FIPS 204⁠ — ML-DSA specification
• malb/lattice-estimator⁠ — Lattice attack cost estimation
• lducas/leaky-LWE-Estimator⁠ — Side-channel leakage analysis
• CRYSTALS-Kyber⁠ — Original Kyber submission
• CRYSTALS-Dilithium⁠ — Original Dilithium submission