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

System Architecture

Overview

Client/Server architecture with blockchain-based vote recording and post-quantum cryptography.

Components

Frontend (Next.js)

• Voting Interface: Election display and ballot selection
• Crypto Client: Paillier encryption and Dilithium signing
• Blockchain Viewer: Display blockchain and verify integrity
• Results Display: Show voting results with proofs

Backend (FastAPI)

• Auth Service: JWT authentication and voter verification
• Voting API: Handle vote submission and blockchain management
• Crypto Service: Paillier key generation, encryption, homomorphic ops
• Blockchain Service: Block creation, chain validation, signature verification
• Scrutator Service: Vote counting and results generation

Database

• Voter Keys: Store Dilithium public keys
• Blockchain Blocks: Persist encrypted votes and signatures
• Emission List: Track voted voters
• Crypto Keys: Store Paillier/Kyber keys

Data Flow

Vote Submission

Frontend (Voter)
  ↓
1. Fetch public keys
  ↓
2. Encrypt ballot (Paillier)
  ↓
3. Generate ZKP
  ↓
4. Sign (Dilithium)
  ↓
Backend (API)
  ↓
5. Verify signature & ZKP
  ↓
6. Check emission list
  ↓
7. Create blockchain block
  ↓
8. Sign block (Dilithium)
  ↓
9. Persist to database
  ↓
10. Return confirmation

Vote Counting

Scrutator
  ↓
1. Fetch blockchain blocks
  ↓
2. Verify chain integrity
  ↓
3. Verify all block signatures
  ↓
4. Homomorphic summation: E(total) = E(v1) × E(v2) × ... × E(vn)
  ↓
5. Decrypt with Paillier private key
  ↓
6. Generate verification proofs
  ↓
7. Publish results

Cryptographic Workflow

Election Setup

1. Generate Paillier keypair (Pu, Pr)
2. Generate Kyber keypair (KPu, KPr) to protect Pr
3. Generate Dilithium keypair (Du, Dr) for block signing
4. Publish (Pu, Du)

Voter Registration

1. Voter authenticates (JWT)
2. Voter generates Dilithium keypair (du, dr)
3. System stores voter's du in database

Ballot Submission

1. Voter selects candidate: v ∈ {0, 1}
2. Frontend: E(v) = Paillier.encrypt(v, Pu)
3. Frontend: π = ZKP.prove(E(v) is 0 or 1)
4. Frontend: σ = Dilithium.sign(E(v) || π, dr)
5. Frontend: submit(voter_id, E(v), π, σ)
6. Backend: verify(σ, du) ✓
7. Backend: verify(π) ✓
8. Backend: check(voter_id not in emission_list) ✓
9. Backend: B = Block(index, prev_hash, timestamp, E(v), tx_id)
10. Backend: σ_block = Dilithium.sign(B, Dr)
11. Backend: blockchain.append(B, σ_block)

Vote Counting

1. C ← retrieve all blocks from blockchain
2. For each block b in C: verify(b.signature, Du)
3. For each block b in C: verify(hash_chain(b.prev_hash))
4. E(total) ← E(0)
5. For each block b in C: E(total) ← E(total) × b.E(v)
6. total ← Paillier.decrypt(E(total), Pr)
7. publish(total, proofs)

Security Properties

Vote Secrecy

• Votes encrypted with Paillier before leaving client
• Server never sees plaintext votes
• Homomorphic summation prevents individual vote leakage

Vote Integrity

• Blockchain structure prevents tampering
• SHA-256 hash chain ensures immutability
• Dilithium signatures verify block authenticity

Voter Authentication

• JWT tokens verify voter session
• Dilithium signatures verify ballot authorship
• Emission list prevents double voting

Anonymity

• Only transaction ID stored with vote (not voter ID)
• Voter verified once at submission
• Homomorphic summation preserves anonymity

Verifiability

• ZKP proves ballot validity without revealing vote
• Anyone can verify blockchain integrity
• Hash chain verification ensures chain validity

Post-Quantum Security

• Kyber protects Paillier private key
• Dilithium signatures resist quantum attacks
• Future-proof against quantum computers

File Structure

backend/
├── crypto_tools.py          # Paillier, Kyber, Dilithium, ZKP
├── blockchain.py            # Block, Blockchain classes
├── routes/
│   ├── votes.py            # Voting endpoints
│   └── auth.py             # Authentication
├── models.py               # Database models
├── services.py             # Business logic
└── scripts/
    └── scrutator.py        # Vote counting

frontend/
├── components/
│   ├── voting-interface.tsx
│   └── blockchain-viewer.tsx
├── lib/
│   ├── crypto-client.ts
│   └── blockchain-verify.ts
└── app/dashboard/
    ├── blockchain/page.tsx
    ├── votes/
    │   ├── active/page.tsx
    │   ├── results/page.tsx
    │   └── history/page.tsx
    └── profile/page.tsx