CIA/e-voting-system/.claude/FAQ.md

FAQ - Questions Fréquemment Posées

🚀 Installation & Démarrage

Q: Par où commencer ?

R:

cd /home/paul/CIA/e-voting-system
./QUICKSTART.sh          # Démarrage rapide
# Ou
make up                  # Démarrage avec make

Q: Quels sont les prérequis ?

R:

• Docker 20.10+
• Docker Compose 1.29+
• Python 3.12 (optionnel, pour développement local)
• 4GB RAM minimum
• 2GB espace disque

Q: Comment accéder à l'application ?

R:

• Frontend : http://localhost:3000
• API : http://localhost:8000
• Documentation API : http://localhost:8000/docs

Q: Erreur "Port déjà utilisé" ?

R:

# Vérifier quel processus utilise le port
lsof -i :3000

# Modifier les ports dans .env ou libérer le port
# Puis redémarrer
docker-compose restart

---

🔐 Cryptographie

Q: Comment fonctionne ElGamal ?

R: ElGamal est un chiffrement asymétrique basé sur le logarithme discret :

• Clé publique : (p, g, h) où h = g^x \bmod p
• Chiffrement : E(m) = (g^r \bmod p, m · h^r \bmod p)
• Propriété clé : Additif homomorphe pour dépouillement sécurisé

Voir rapport/main.typ pour détails mathématiques.

Q: Pourquoi ElGamal et pas Paillier ?

R: Pour ce prototype, ElGamal offre :

• Suffisant pour votes binaires (0 ou 1)
• Plus simple à comprendre
• Calcul plus rapide

Paillier serait meilleur pour :

• Votes multi-candidats complexes
• Opérations plus flexibles

Q: Les signatures RSA-PSS sont-elles sûres ?

R: Oui, RSA-PSS avec :

• Taille clé : 2048 bits (protocole)
• Fonction de hash : SHA-256
• Salt aléatoire (probabiliste)
• Résistant aux attaques par timing

Q: Comment les preuves ZK fonctionnent ?

R: Protocole Fiat-Shamir non-interactif :

1. Prouver qu'on connaît un secret
2. Sans le révéler
3. Utilisant un hash comme défi

Cas d'usage : prouver qu'un vote est valide sans le dévoiler.

---

🗳️ Processus de Vote

Q: Comment assurer l'anonymat ?

R:

• Vote chiffré avec ElGamal
• Hash unique du bulletin
• Pas de lien entre voter et vote
• Résultats déchiffrés seulement après clôture

Q: Peut-on voter deux fois ?

R: Non, protections multiples :

• Contrainte UNIQUE base de données (voter_id, election_id)
• Flag has_voted sur électeur
• Vérification backend

Q: Peut-on modifier mon vote ?

R: Non :

• Vote chiffré immédiatement
• Hachage SHA-256 pour intégrité
• Stocké en base sécurisé
• Vérification avant dépouillement

Q: Comment sont comptabilisés les votes ?

R:

1. Tous les votes restent chiffrés
2. Somme via propriété homomorphe ElGamal
3. Déchiffrement final du résultat
4. Publication sans détails individuels

---

🐳 Docker & Déploiement

Q: Combien de conteneurs ?

R: 3 services :

• frontend : Port 3000 (HTML5 + JS)
• backend : Port 8000 (FastAPI)
• mariadb : Port 3306 (Données)

Q: Comment sauvegarder la base de données ?

R:

docker-compose exec mariadb mysqldump -u evoting_user -p evoting_db > backup.sql

# Restaurer
docker-compose exec -T mariadb mysql -u evoting_user -p evoting_db < backup.sql

Q: Puis-je déployer en production ?

R: Oui, mais appliquez ces recommandations :

1. Secrets :

   export DB_PASSWORD=$(openssl rand -hex 16)
   export SECRET_KEY=$(openssl rand -hex 32)
   

2. HTTPS : Configurez TLS/SSL

3. CORS : Restreindre les origines

   CORS_ORIGINS="https://vote.company.com"
   

4. Logs : Centraliser (ELK, Loki)

5. Monitoring : Alertes (Prometheus)

Voir DEPLOYMENT.md pour détails.

Q: Comment scaler horizontalement ?

R:

# docker-compose.yml
backend:
  deploy:
    replicas: 3  # 3 instances backend

# Ajouter Load Balancer (Nginx)
nginx:
  image: nginx:alpine
  ports:
    - "80:80"
  # Config upstream les 3 backend

---

🧪 Tests & Développement

Q: Comment lancer les tests ?

R:

make test              # Tous les tests
make test -k test_elgamal   # Tests spécifiques
make lint              # Vérifier la qualité
make format            # Formater le code

Q: Comment développer localement ?

R:

make install           # Installer Poetry
make dev              # Backend en mode watch
# Frontend est servi par le conteneur Docker

Q: Tests d'intégrité réussis ?

R: Tests présents :

• ✅ ElGamal encrypt/decrypt
• ✅ Homomorphic addition
• ✅ RSA signatures
• ✅ ZK proofs
• ✅ SHA-256 hashing

À développer :

• Backend API integration tests
• End-to-end voting flow

Q: Comment contribuer ?

R: Voir CONTRIBUTING.md :

1. Fork le repo
2. Créer branche feature
3. Écrire tests
4. Faire PR sur dev
5. Review & merge

---

🔍 Troubleshooting

Q: "Connection refused" au backend ?

R:

# Vérifier que le conteneur tourne
docker-compose ps

# Voir les logs
docker-compose logs backend

# Redémarrer
docker-compose restart backend

Q: MariaDB ne démarre pas ?

R:

# Réinitialiser la BD
docker-compose down -v
docker-compose up -d

# Attendre 30s pour initialisation SQL
sleep 30

Q: "Module not found" Python ?

R:

make install           # Réinstaller
poetry install         # Ou directement

# Vérifier l'env
poetry env info

Q: Le Frontend n'affiche rien ?

R:

• Vérifier http://localhost:3000
• Vérifier les logs : docker-compose logs frontend
• Vérifier backend accessible : http://localhost:8000/health

Q: Erreurs CORS ?

R:

# Dans .env, ajouter
CORS_ORIGINS="http://localhost:3000"

# Redémarrer backend
docker-compose restart backend

---

📊 Performance

Q: Combien de votes par seconde ?

R: Prototype :

• ~10 votes/sec (avec crypto)
• ElGamal encrypt : ~10ms
• BD insert : ~5ms
• Total : ~15ms/vote

Optimisations en prod :

• Pré-calcul exponentiations
• Connection pooling
• Indexes BD

Q: Scalabilité ?

R:

• Horizontale : Ajouter backend replicas
• Verticale : Plus de CPU/RAM
• Limite réelle : BD (considérer sharding)

Q: Déployer 100k électeurs ?

R: Oui, avec :

• 3+ replicas backend
• Pool conexiones 50+
• Indexes optimisés
• Éventuellement : Redis cache

---

🔐 Sécurité

Q: Les données en transit sont-elles sécurisées ?

R:

• Votes chiffrés ElGamal avant envoi
• Tokens JWT avec signature
• HTTPS en production (obligatoire)

Q: Peut-on compromettre le système ?

R: Menaces mitigées :

Menace	Mitigation
Modification votes	Chiffrement ElGamal
Révélation votes	Anonymat + ZK-proofs
Usurpation identité	JWT + bcrypt
Double vote	Contrainte unique BD
Révélation données	Audit logs

Q: Comment auditer le système ?

R:

• Journal complet : audit_logs table
• Traces IP/timestamp
• Vérification preuves ZK
• Vérification hashes

Q: Mettre à jour les dépendances ?

R:

poetry update                    # Mettre à jour
poetry audit                    # Vérifier CVE
docker-compose build --no-cache # Rebuild images

---

📚 Documentation

Q: Où trouver la documentation ?

R:

• README.md : Vue d'ensemble
• PROJECT_SUMMARY.md : Récapitulatif
• QUICKSTART.sh : Démarrage rapide
• DEPLOYMENT.md : Déploiement
• ARCHITECTURE.md : Système détaillé
• CONTRIBUTING.md : Contribution
• rapport/main.typ : Rapport complet (30+ pages)

Q: Comment générer le PDF du rapport ?

R:

# Installer typst
cargo install typst-cli

# Compiler
typst compile rapport/main.typ rapport/main.pdf

Q: Le rapport est où ?

R: Dans rapport/main.typ (Typst format)

• Spécifications techniques
• Fondamentaux cryptographiques
• Architecture
• Analyse de sécurité
• Tests et validation

---

🎯 Général

Q: Durée du projet ?

R:

• Backend + Crypto : 40%
• Frontend : 20%
• Tests : 15%
• Documentation : 15%
• Déploiement : 10%

Q: Peut-on réutiliser le code ?

R: Oui, licence MIT :

• Utilisez librement
• Modifiez comme vous voulez
• Attribution appréciée

Q: Peut-on déployer en production réelle ?

R: Théoriquement oui, pratiquement :

• Besoin audit sécurité externe
• Besoin compliance légale
• Besoin scalabilité supérieure
• Considérer blockchain pour immuabilité

Q: Existe-t-il des alternatives connues ?

R: Oui :

• Helios (MIT, basé ZK)
• Belenios (Française, blockchain)
• SpeediVote (Suisse)
• Voatz (USA)

Q: Comment contribuer au projet ?

R:

1. Lire CONTRIBUTING.md
2. Cloner le repo
3. Créer branche feature
4. Écrire tests
5. Faire PR

---

Merci d'utiliser e-Voting System ! 🗳️

Pour plus d'infos : https://github.com/... Contact : support@...