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

System Architecture

Overview

Client/Server architecture with blockchain-based vote recording and cryptographic security. Built with Next.js 15 frontend and FastAPI backend.

Components (Implemented)

Frontend (Next.js 15 + TypeScript)

• ✅ Voting Interface (components/voting-interface.tsx): Multi-step ballot selection and submission
• ✅ Crypto Client (lib/crypto-client.ts): ElGamal encryption, ZKP generation, digital signatures
• ✅ Authentication: JWT-based voter sessions
• ⏳ Blockchain Viewer: Display blockchain and verify integrity (UI pending)
• ⏳ Results Display: Show voting results with verification proofs (UI pending)

Backend (FastAPI + Python 3.12)

• ✅ Auth Service (routes/auth.py): JWT authentication and voter verification
• ✅ Voting API (routes/votes.py): Vote submission, encryption, blockchain recording
• ✅ Blockchain Service (blockchain.py): Block creation, chain validation, integrity verification
• ✅ Crypto Operations: ElGamal encryption, digital signatures, SHA-256 hashing, ZKP
• ✅ Scrutator Service (scripts/scrutator.py): Vote counting, verification, and audit reporting
• ✅ Election Service (routes/elections.py): Election management

Database (SQLAlchemy)

• ✅ Voter: Voter registration and authentication
• ✅ Election: Election configuration and cryptographic keys
• ✅ Candidate: Election options
• ✅ Vote: Encrypted votes with ballot hashes and ZK proofs
• ✅ AuditLog: Security audit trail

Data Flow (Implemented)

Vote Submission

Frontend (Voter)
  ↓ GET /api/votes/public-keys
Backend
  ↓ Return ElGamal public key
  ↓
Frontend:
  1. ✅ Fetch public keys
  ↓
  2. ✅ Encrypt ballot (ElGamal)
  ↓
  3. ✅ Generate ZKP (Fiat-Shamir)
  ↓
  4. ✅ Sign ballot (RSA-PSS)
  ↓
  5. ✅ Submit POST /api/votes/submit
  ↓
Backend (API):
  ↓
  6. ✅ Authenticate voter (JWT)
  ↓
  7. ✅ Verify signature (RSA-PSS)
  ↓
  8. ✅ Verify ZKP
  ↓
  9. ✅ Check voter hasn't voted
  ↓
  10. ✅ Create blockchain block
  ↓
  11. ✅ Sign block (RSA-PSS)
  ↓
  12. ✅ Append to blockchain
  ↓
  13. ✅ Record in database
  ↓
  14. ✅ Return transaction_id
  ↓
Frontend:
  ↓ Display confirmation with TX ID

Vote Counting (Scrutator)

Command: poetry run python -m backend.scripts.scrutator --election-id 1
  ↓
Scrutator Service:
  ↓
  1. ✅ Load election and blockchain
  ↓
  2. ✅ Fetch all votes from database
  ↓
  3. ✅ Verify blockchain integrity:
     - Check hash chain (each block refs previous)
     - Check block signatures
     - Detect any tampering
  ↓
  4. ✅ Count votes by candidate
  ↓
  5. ✅ Verify consistency (DB votes == blockchain votes)
  ↓
  6. ✅ Generate audit report:
     - Blockchain validity
     - Vote counts
     - Verification proofs
     - Timestamp
  ↓
  7. ✅ Export JSON report

Cryptographic Workflow (Implemented)

Election Setup (Endpoint: POST /api/votes/setup)

1. ✅ Generate ElGamal keypair (p, g, h) where h = g^x mod p
2. ✅ Store public key p in election record
3. ✅ Create blockchain for election
4. ✅ Publish public key to voters Post-Quantum Ready: Kyber and Dilithium support via liboqs-python (optional)

Voter Registration

1. ✅ Voter authenticates (JWT token)
2. ✅ Voter registration stored in database
3. ✅ System verifies voter hasn't voted in this election

Ballot Submission (Endpoint: POST /api/votes/submit)

Voter:
1. ✅ Voter selects candidate: v ∈ {0, 1}

Frontend (crypto-client.ts):
2. ✅ GET /api/votes/public-keys?election_id=1
3. ✅ E(v) = ElGamal.encrypt(v, pubkey)
4. ✅ π = ZKP.prove(E(v) is 0 or 1)  [Fiat-Shamir protocol]
5. ✅ σ = sign(E(v) || π)  [RSA-PSS]
6. ✅ POST /api/votes/submit {election_id, candidate_id, encrypted_vote, zkp_proof, signature}

Backend (routes/votes.py):
7. ✅ Authenticate voter (verify JWT)
8. ✅ Validate encrypted vote format
9. ✅ Verify ZKP proof (check challenge-response)
10. ✅ Check voter hasn't voted (emission list check)
11. ✅ Create Block(index, prev_hash, timestamp, E(v), tx_id)
12. ✅ H = SHA256(Block contents)  [hash chain]
13. ✅ σ_block = sign(H)  [block signature]
14. ✅ blockchain.add_block(H, σ_block)  [append to chain]
15. ✅ Record Vote in database
16. ✅ Return {transaction_id, block_index, confirmation}

Vote Counting (Command: poetry run python -m backend.scripts.scrutator --election-id 1)

Scrutator (scripts/scrutator.py):
1. ✅ Load blockchain for election
2. ✅ Fetch all votes from database
3. ✅ For each block b in blockchain:
     - ✅ Verify(b.signature)  [block authenticity]
     - ✅ Verify(H = SHA256(block_content))  [block integrity]
     - ✅ Verify(b.prev_hash == previous_block.H)  [chain linkage]
4. ✅ If any verification fails: BLOCKCHAIN INVALID
5. ✅ Count votes by candidate from database
6. ✅ Verify consistency: |database_votes| == |blockchain_blocks|
7. ✅ Generate audit report:
     - Blockchain validity status
     - Vote counts with percentages
     - Verification proofs
     - Timestamp and signatures
8. ✅ Export JSON report for transparency

Security Properties (Implemented)

✅ Vote Secrecy

• Votes encrypted with ElGamal before leaving client (crypto-client.ts)
• Server never sees plaintext votes (encrypted_vote stored as base64)
• Vote linked to candidate in database only for counting (not in blockchain)
• Mechanism: ElGamal(vote) = (g^r mod p, vote * h^r mod p) is semantically secure

✅ Vote Integrity

• Blockchain structure prevents tampering (blockchain.py)
• SHA-256 hash chain ensures immutability (each block refs previous)
• RSA-PSS signatures verify block authenticity
• Modification of any block breaks entire chain
• Verification: Any block tampering detected by hash verification

✅ Voter Authentication

• JWT tokens verify voter session (auth.py)
• RSA-PSS signatures verify ballot authorship (crypto-client.ts)
• Emission list prevents double voting (check before recording)
• Voter must authenticate before voting

✅ Anonymity

• Only transaction ID stored with vote in blockchain (not voter ID)
• Voter verified once at authentication
• Vote-to-voter link exists only in database (not blockchain)
• Blockchain itself is voter-anonymous
• Mechanism: Transaction ID = random 12-hex string, unlinked to voter

✅ Individual Verifiability

• ZKP proves ballot validity (0 or 1) without revealing vote (zk_proofs.py)
• Voter can search blockchain for their transaction ID
• Voter can verify their encrypted ballot is recorded
• Mechanism: Fiat-Shamir ZKP challenge-response protocol

✅ Universal Verifiability

• Blockchain is public (GET /api/votes/blockchain)
• Anyone can verify chain integrity (verify_chain_integrity())
• Anyone can run scrutator to verify vote counting
• Hash chain verification ensures chain validity
• Mechanism: SHA-256 chain links every block to previous; modify one block = hash mismatch

✅ Post-Quantum Ready

• Kyber support in pqc_hybrid.py (requires liboqs-python)
• Dilithium support in pqc_hybrid.py (requires liboqs-python)
• Currently uses RSA (classical) - PQC available as drop-in replacement
• Future-proof architecture ready for quantum-resistant migration

File Structure (Implemented)

backend/
├── blockchain.py            # ✅ Block, Blockchain classes with integrity verification
├── crypto/
│   ├── encryption.py        # ✅ ElGamal homomorphic encryption
│   ├── signatures.py        # ✅ RSA-PSS digital signatures
│   ├── hashing.py           # ✅ SHA-256 hashing and key derivation
│   ├── zk_proofs.py         # ✅ Fiat-Shamir zero-knowledge proofs
│   └── pqc_hybrid.py        # ✅ Post-quantum crypto (Kyber, Dilithium)
├── routes/
│   ├── votes.py             # ✅ Complete voting API endpoints
│   ├── elections.py         # ✅ Election management
│   └── auth.py              # ✅ Authentication
├── models.py                # ✅ Database models (Voter, Election, Vote, etc)
├── services.py              # ✅ Business logic services
├── database.py              # ✅ Database configuration
├── main.py                  # ✅ FastAPI app initialization
├── config.py                # ✅ Configuration
├── auth.py                  # ✅ JWT token handling
└── scripts/
    └── scrutator.py         # ✅ Vote counting, verification, audit reporting

frontend/
├── components/
│   └── voting-interface.tsx # ✅ Multi-step voting interface (select→confirm→submit→success)
├── lib/
│   ├── crypto-client.ts     # ✅ Client-side encryption, ZKP, signatures
│   ├── api.ts               # ✅ API client with type-safe interfaces
│   ├── auth-context.tsx     # ✅ Authentication context
│   └── validation.ts        # ✅ Form validation
├── app/
│   ├── auth/
│   │   ├── login/page.tsx           # ✅ Login page
│   │   └── register/page.tsx        # ✅ Registration page
│   └── dashboard/
│       ├── page.tsx                 # ✅ Dashboard home
│       ├── profile/page.tsx         # ✅ Profile page
│       └── votes/
│           ├── active/page.tsx      # ✅ Active elections
│           ├── upcoming/page.tsx    # ✅ Upcoming elections
│           ├── history/page.tsx     # ✅ Vote history
│           └── archives/page.tsx    # ✅ Past elections
└── public/                  # ✅ Static assets

Infrastructure:
├── docker-compose.yml       # ✅ Docker configuration
├── Dockerfile               # ✅ Backend Docker image
├── frontend/Dockerfile      # ✅ Frontend Docker image
├── pyproject.toml           # ✅ Python dependencies (Poetry)
└── openspec/                # ✅ Specification and change tracking
    ├── specs/
    │   ├── mvp.md          # ✅ MVP implementation spec
    │   └── architecture.md # ✅ Architecture documentation
    └── changes/
        └── add-pqc-voting-mvp/
            ├── proposal.md
            ├── tasks.md
            └── design.md