CIA/e-voting-system/openspec/specs/mvp.md

MVP Specification - E-Voting System

Overview

Minimum Viable Product for secure electronic voting with blockchain and post-quantum cryptography.

Implemented Features

Core Cryptographic Components

• ✅ ElGamal Homomorphic Encryption: Vote encryption and homomorphic operations (MVP uses ElGamal, Paillier architecture compatible)
• ✅ Zero-Knowledge Proofs: Fiat-Shamir protocol proving ballot validity (0 or 1) without revealing vote
• ✅ Digital Signatures: RSA-PSS signatures for ballot authentication and blockchain block signing
• ✅ Secure Hashing: SHA-256 for blockchain hash chain and ballot identification
• ✅ Blockchain: Immutable vote recording with linked hash chain (SHA-256)

Post-Quantum Ready (Optional):

• Kyber (ML-KEM): Post-quantum key encapsulation (architecture ready, depends on liboqs-python)
• Dilithium (ML-DSA): Post-quantum digital signatures (architecture ready, depends on liboqs-python)

API Endpoints (Implemented)

POST   /api/votes/setup                 # ✅ Initialize election with crypto keys
GET    /api/votes/public-keys           # ✅ Retrieve public keys for encryption
POST   /api/votes/submit                # ✅ Submit encrypted ballot with ZKP & signature
GET    /api/votes/blockchain            # ✅ Get blockchain state with verification
GET    /api/votes/results               # ✅ Get vote results with verification proofs
POST   /api/votes/verify-blockchain     # ✅ Verify blockchain integrity
GET    /api/votes/status                # ✅ Check voter voting status
GET    /api/votes/history               # ✅ Get voter vote history

Frontend Features (Implemented)

• ✅ Election details display
• ✅ Client-side ballot encryption (ElGamal)
• ✅ Zero-knowledge proof generation
• ✅ Ballot signing and submission
• ✅ Multi-step voting interface (select → confirm → submit → success)
• ✅ Vote confirmation with security notices
• ✅ Transaction ID tracking for verification
• ✅ Error handling and user feedback

Backend Modules (Implemented)

• ✅ backend/blockchain.py: Blockchain data structure with integrity verification
• ✅ backend/routes/votes.py: Complete voting API with blockchain integration
• ✅ backend/scripts/scrutator.py: Vote counting, verification, and audit reporting
• ✅ backend/crypto/encryption.py: ElGamal homomorphic encryption
• ✅ backend/crypto/signatures.py: Digital signature operations
• ✅ backend/crypto/hashing.py: SHA-256 hashing and key derivation
• ✅ backend/crypto/zk_proofs.py: Zero-knowledge proof implementation

Frontend Components (Implemented)

• ✅ frontend/lib/crypto-client.ts: Client-side cryptographic operations
• ✅ frontend/components/voting-interface.tsx: Complete voting interface component

Security Properties

Property	Mechanism	Guarantee
Vote Secrecy	ElGamal Encryption	Votes encrypted before leaving client; server never sees plaintext
Vote Integrity	Blockchain + Signatures	Immutable blocks with SHA-256 chain; any tampering breaks chain
Anonymity	Transaction IDs	Voter ID verified once at authentication; TX ID used in blockchain instead
Individual Verifiability	ZKP + Blockchain	Voter can verify their encrypted ballot in blockchain
Universal Verifiability	Public Blockchain	Anyone can verify chain integrity and vote counting
Authentication	Digital Signatures	Ballots signed; blocks signed by authority
Post-Quantum Ready	Kyber + Dilithium	Architecture supports PQC (optional, conditional on library)

Implementation Status

Phase 1: Cryptographic Foundations ✅ COMPLETE

• ✅ ElGamal homomorphic encryption with key generation, encryption/decryption, homomorphic addition
• ✅ Zero-Knowledge Proofs using Fiat-Shamir protocol
• ✅ Digital signatures using RSA-PSS
• ✅ SHA-256 hashing for blockchain and ballot identification
• ✅ Blockchain module with Block and Blockchain classes
• ✅ Chain integrity verification with hash chain validation

Phase 2: Backend API ✅ COMPLETE

• ✅ All voting endpoints implemented and registered
• ✅ Blockchain integration with vote recording
• ✅ Vote duplication prevention (one vote per election per voter)
• ✅ Election initialization with key generation
• ✅ Public key distribution for client-side encryption
• ✅ Results calculation with verification
• ✅ Blockchain verification endpoints

Phase 3: Frontend Interface ✅ COMPLETE

• ✅ Voting interface component with multi-step workflow
• ✅ Client-side ballot encryption
• ✅ Zero-knowledge proof generation
• ✅ Ballot signing and submission
• ✅ Vote confirmation workflow
• ✅ Error handling and user feedback
• ✅ Transaction ID tracking

Phase 4: Blockchain Visualization ⏳ PENDING

• Vote counting and scrutiny module (scrutator.py) ✅ implemented
• Blockchain viewer UI component ⏳ pending
• Blockchain block display pages ⏳ pending
• Chain verification UI ⏳ pending

Phase 5: Results & Reporting ⏳ PENDING

• Results API endpoint ✅ implemented
• Results display page ⏳ pending
• Verification proof display ⏳ pending
• Audit trail visualization ⏳ pending

Phase 6: Testing & Documentation ⏳ PENDING

• Unit tests for crypto operations ✅ exist (test_crypto.py, test_pqc.py)
• Integration tests ⏳ pending (test_backend.py is skeleton)
• Technical & scientific report ⏳ pending
• Docker deployment ✅ configured (docker-compose.yml exists)

Build Status

• ✅ Frontend: Builds successfully with TypeScript
• ✅ Backend: All modules import correctly
• ✅ Dependencies: Poetry lock file generated and validated
• ✅ No breaking changes to existing code
• ✅ All new endpoints registered and functional

Known Limitations (MVP Scope)

1. No Persistent Blockchain: Blockchain stored in memory per application instance (suitable for demo/testing)
2. No Distributed Consensus: Single-authority blockchain (suitable for election official)
3. No Voter Key Management: Simple voter registration without per-voter crypto keys
4. No Encrypted Results: Results calculated from plaintext vote counts (not homomorphically)
5. Optional PQC: Post-quantum algorithms available when liboqs-python library installed