diff --git a/e-voting-system/openspec/project.md b/e-voting-system/openspec/project.md index d9df6c6..cf9b73f 100644 --- a/e-voting-system/openspec/project.md +++ b/e-voting-system/openspec/project.md @@ -58,10 +58,106 @@ Conceive and implement a functional prototype of a secure electronic voting syst - **Development Server**: uvicorn (backend), Next.js dev (frontend) - **Production Build**: Next.js static export + Node.js server +### Cryptography Libraries +- **Paillier Homomorphic Encryption**: `python-paillier` - Vote encryption & homomorphic summation +- **Kyber (ML-KEM)**: `liboqs-python` - Post-quantum key encapsulation +- **Dilithium (ML-DSA)**: `liboqs-python` - Post-quantum digital signatures +- **SHA-256**: Built-in hashlib - Blockchain hashing +- **ZKP (Zero-Knowledge Proofs)**: Custom implementation - Ballot validity proofs + ### Blockchain/Distributed Ledger - Vote records stored with ballot hashes -- Immutable vote recording +- Immutable vote recording via linked blocks - Transparent result verification +- Chain integrity verification via SHA-256 hashing +- Block signatures with Dilithium PQC + +## MVP (Minimum Viable Product) Features + +### Core Components + +**1. Cryptographic Toolkit (`backend/crypto_tools.py`)** +- Paillier homomorphic encryption (key generation, encryption, decryption, homomorphic addition) +- Kyber (ML-KEM) for post-quantum key encapsulation +- Dilithium (ML-DSA) for post-quantum digital signatures +- Simple Zero-Knowledge Proofs (prove ballot is 0 or 1 without revealing value) +- SHA-256 for blockchain hashing + +**2. Blockchain Module (`backend/blockchain.py`)** +- Block structure: index, previous hash, timestamp, encrypted votes, block hash, signature +- Chain validation: verify hash chain integrity and block signatures +- Ballot addition: add new encrypted votes to blockchain +- Chain immutability: ensure votes cannot be altered + +**3. Voting API Endpoints (`backend/routes/votes.py`)** +- `POST /api/votes/setup` - Initialize election (generate Paillier keys) +- `GET /api/votes/public-keys` - Retrieve public keys for client encryption +- `POST /api/votes/submit` - Submit encrypted ballot with signature +- `GET /api/votes/blockchain` - Retrieve blockchain state +- `GET /api/votes/count` - Homomorphic vote counting + +**4. Voter Client (`frontend/components/voting-interface.tsx`)** +- Display election details and candidates +- Client-side ballot encryption with Paillier +- Generate simple ZKP for ballot validity +- Sign ballot with voter's Dilithium key +- Submit encrypted, signed ballot to blockchain +- Display confirmation and vote receipt + +**5. Blockchain Visualizer (`frontend/app/dashboard/blockchain/page.tsx`)** +- Display blockchain as linked blocks +- Show: block index, previous hash, current hash, encrypted vote, signature +- Chain integrity verification button +- Visual representation of vote count progress + +**6. Scrutator Module (`backend/scripts/scrutator.py`)** +- Access blockchain votes +- Verify chain integrity and all signatures +- Homomorphic summation: multiply all encrypted votes to get encrypted total +- Decrypt result using Paillier private key (protected by Kyber) +- Publish results with verification proofs + +### MVP Voting Process + +**Étape 1: Election Setup** +- System generates Paillier keypair +- System generates Kyber keypair for private key protection +- System generates Dilithium keypair for block signing +- Public keys published for voters + +**Étape 2: Voter Registration & Key Generation** +- Voter authenticates via JWT +- Voter generates personal Dilithium keypair +- System stores public key for vote verification + +**Étape 3: Voter's Ballot Submission** +1. Voter selects candidate (0 or 1) +2. Frontend encrypts ballot: `E(v) = Paillier.encrypt(v, public_key)` +3. Frontend generates ZKP: proof that `E(v)` is valid (0 or 1) +4. Frontend signs: `Signature = Dilithium.sign(E(v) || ZKP, voter_private_key)` +5. Frontend submits: `{voter_id, E(v), ZKP, Signature}` to API +6. API verifies signature and ZKP +7. API checks voter hasn't already voted (emission list) +8. API adds to blockchain: `Block{index, prev_hash, timestamp, E(v), tx_id, block_signature}` +9. API returns confirmation + +**Étape 4: Vote Counting (Scrutator)** +1. Retrieve all blocks from blockchain +2. Verify blockchain integrity (hash chain + all block signatures) +3. Homomorphic operation: `E(total) = E(v1) × E(v2) × ... × E(vn)` +4. Decrypt: `total = Paillier.decrypt(E(total), private_key)` +5. Publish results + +### Security Properties Provided + +| Property | Mechanism | Implementation | +|----------|-----------|-----------------| +| **Vote Secrecy** | Paillier encryption | Votes encrypted before leaving client | +| **Vote Integrity** | Blockchain + Dilithium signatures | Linked blocks + PQC signatures on blocks | +| **Voter Authentication** | JWT tokens + Dilithium signatures | JWT for session, Dilithium for ballot auth | +| **Anonymity** | Transaction ID instead of voter ID | Voter ID verified once, not stored with vote | +| **Verifiability** | ZKP + blockchain verification | Client proves ballot validity, anyone verifies chain | +| **Post-Quantum Ready** | Kyber + Dilithium | Protected against future quantum attacks | ## Project Conventions @@ -312,3 +408,229 @@ docs: Add comprehensive project status document - Backend ReDoc: `GET /redoc` - Frontend: `http://localhost:3000` - Backend: `http://localhost:8000` + +## Implementation Plan + +### Phase 1: Cryptographic Foundations +**Goal**: Build secure crypto toolkit for PQC-based voting + +**Tasks**: +1. Create `backend/crypto_tools.py` with: + - Paillier homomorphic encryption (key generation, encrypt, decrypt, homomorphic ops) + - Kyber (ML-KEM) integration via liboqs-python + - Dilithium (ML-DSA) integration via liboqs-python + - Simple ZKP implementation (prove 0 or 1 without revealing) + - SHA-256 blockchain hashing utilities + +2. Create `backend/blockchain.py` with: + - Block class (index, prev_hash, timestamp, encrypted_votes, block_hash, signature) + - Blockchain class (chain management, validation, immutability) + - Hash verification and signature verification methods + - Homomorphic vote summation + +3. Update `requirements.txt`: + - `python-paillier` + - `liboqs-python` + - `pycryptodome` for additional crypto utilities + +**Deliverables**: +- ✅ Functional crypto toolkit +- ✅ Blockchain data structure +- ✅ Unit tests for crypto operations + +--- + +### Phase 2: Backend API Integration +**Goal**: Implement secure voting endpoints + +**Tasks**: +1. Update `backend/routes/votes.py`: + - `POST /api/votes/setup` - Initialize election, generate Paillier/Kyber/Dilithium keys + - `GET /api/votes/public-keys` - Return public keys for client encryption + - `POST /api/votes/register-voter` - Register voter, generate their Dilithium keys + - `POST /api/votes/submit` - Receive encrypted ballot, verify signature, add to blockchain + - `GET /api/votes/blockchain` - Return blockchain state for verification + - `GET /api/votes/results` - Run scrutator, return homomorphic count + +2. Update `backend/models.py`: + - Add Dilithium key storage for voters + - Add blockchain block storage + - Add vote submission tracking (emission list) + +3. Create `backend/scripts/scrutator.py`: + - Verify blockchain integrity + - Compute homomorphic sum + - Decrypt final results + - Generate verification report + +**Deliverables**: +- ✅ Secure API endpoints +- ✅ Blockchain persistence +- ✅ Vote scrutiny module + +--- + +### Phase 3: Frontend Voting Interface +**Goal**: Build client-side secure voting experience + +**Tasks**: +1. Create `frontend/components/voting-interface.tsx`: + - Display election details + - Fetch public keys from backend + - Client-side Paillier encryption + - Generate ballot validity ZKP + - Sign with voter's Dilithium key + - Submit encrypted ballot + - Show vote confirmation + +2. Create `frontend/lib/crypto-client.ts`: + - Paillier encryption operations + - Dilithium signature operations + - ZKP generation + - Ballot serialization + +3. Update `frontend/app/dashboard/votes/active/page.tsx`: + - Integrate voting interface + - Show election details + - Display vote submission form + +**Deliverables**: +- ✅ Secure voting UI +- ✅ Client-side crypto operations +- ✅ Vote submission workflow + +--- + +### Phase 4: Blockchain Visualization & Verification +**Goal**: Display blockchain and enable verification + +**Tasks**: +1. Create `frontend/app/dashboard/blockchain/page.tsx`: + - Fetch blockchain from API + - Display blocks as linked chain + - Show: index, prev_hash, current_hash, encrypted_vote, signature + - Display vote count progress + - Integrity verification button + +2. Create `frontend/components/blockchain-viewer.tsx`: + - Block display component + - Chain visualization + - Hash verification UI + +3. Create `frontend/lib/blockchain-verify.ts`: + - Verify hash chain locally + - Verify block signatures + - Display verification results + +**Deliverables**: +- ✅ Blockchain visualization +- ✅ Verification interface +- ✅ Results display + +--- + +### Phase 5: Results & Reporting +**Goal**: Display counting results and verification proofs + +**Tasks**: +1. Create `frontend/app/dashboard/votes/results/page.tsx`: + - Display final vote count + - Show homomorphic verification + - Display blockchain integrity report + - Show audit trail + +2. Update backend scrutator: + - Generate detailed results + - Create verification proofs + - Provide transparency report + +**Deliverables**: +- ✅ Results display page +- ✅ Verification proofs +- ✅ Audit report + +--- + +### Phase 6: Testing & Documentation +**Goal**: Ensure security and create technical report + +**Tasks**: +1. Create technical report document: + - Section 1: Introduction & Design Choices + - Motivation and e-voting challenges + - System architecture (client/server + blockchain) + - Technology justification + - Voting process walkthrough + + - Section 2: Analysis & Cryptographic Application + - Explain Paillier homomorphic encryption + - Explain Kyber (ML-KEM) key encapsulation + - Explain Dilithium (ML-DSA) signatures + - Explain simple ZKP implementation + - Explain blockchain hashing + - How crypto tools guarantee properties + + - Section 3: Security Properties & Threat Analysis + - Security properties provided + - Threat analysis and mitigation + - Resistance evaluation + +2. Add tests: + - Unit tests for crypto operations + - Integration tests for voting workflow + - Blockchain integrity tests + +3. Docker testing: + - Ensure full deployment via docker-compose + - Test all endpoints + - Verify blockchain functionality + +**Deliverables**: +- ✅ Complete technical & scientific report +- ✅ Test suite +- ✅ Deployment documentation + +--- + +## Development Progress Tracking + +### Phase 1: Cryptographic Foundations +- [ ] Paillier toolkit implementation +- [ ] Kyber integration +- [ ] Dilithium integration +- [ ] ZKP implementation +- [ ] Blockchain module +- [ ] Crypto tests + +### Phase 2: Backend API Integration +- [ ] Voting endpoints +- [ ] Database models +- [ ] Blockchain persistence +- [ ] Scrutator module +- [ ] API tests + +### Phase 3: Frontend Voting Interface +- [ ] Voting component +- [ ] Crypto client library +- [ ] Vote submission flow +- [ ] Confirmation display + +### Phase 4: Blockchain Visualization +- [ ] Blockchain viewer page +- [ ] Block display component +- [ ] Verification UI +- [ ] Hash verification + +### Phase 5: Results & Reporting +- [ ] Results page +- [ ] Verification proofs +- [ ] Audit report +- [ ] Results display + +### Phase 6: Testing & Documentation +- [ ] Technical report (Section 1) +- [ ] Technical report (Section 2) +- [ ] Technical report (Section 3) +- [ ] Unit tests +- [ ] Integration tests +- [ ] Docker verification