Intégration du serveur

Processus de vérification PoW

Le processus de vérification repose sur un travail computationnel (hachage SHA) et comprend les étapes suivantes :

Récupérer le challenge du côté client.
Déterminer la solution au challenge.
Soumettre à la fois la solution et les données utilisateur au serveur.
Valider la solution et la signature du serveur.

L’aspect côté client est géré par le widget ALTCHA, tandis que la mise en œuvre de la vérification côté serveur est requise. Le gestionnaire de soumission du serveur (par exemple, POST /form_submit) doit authentifier la charge utile ALTCHA lors de la soumission du formulaire.

Consultez la documentation de preuve de travail pour en savoir plus sur le mécanisme derrière ALTCHA.

Complexité

Générer un nouveau challenge implique trois passes de calcul SHA (une fois pour le challenge et deux fois pour la signature HMAC). De même, la vérification d’une solution nécessite également trois passes.

La plage du nombre aléatoire ajuste la difficulté de la tâche computationnelle requise du client.

Pour plus de détails, consultez l’ajustement de la complexité.

Serveur

Le serveur doit générer un nouveau challenge pour chaque vérification ALTCHA. Il existe deux méthodes pour fournir le challenge au widget :

Utilisation de challengeurl : Si configuré, le widget récupère le challenge à partir de l’URL spécifiée. Le serveur doit renvoyer un nouveau challenge comme décrit ci-dessous.
Utilisation de challengejson : Fournir directement le challenge sous forme de chaîne encodée en JSON. Cette méthode est utile pour les pages rendues côté serveur.

En savoir plus sur le mécanisme de preuve de travail.

Création d’un challenge

Voici un exemple de pseudo-code pour créer un challenge sur le serveur :

// Générer un sel aléatoire (longueur recommandée : au moins 10 caractères)
salt = random_string();

// Générer un nombre secret aléatoire (entier positif)
// La plage dépend de la complexité choisie (voir la documentation)
// Assurez-vous de ne pas exposer ce nombre au client
secret_number = random_int();

// Calculer le hachage SHA256 du sel concaténé + du nombre secret (résultat encodé en chaîne HEX)
challenge = sha2_hex(concat(salt, secret_number));

// Créer une signature serveur en utilisant une clé HMAC (résultat encodé en chaîne HEX)
signature = hmac_sha2_hex(challenge, hmac_key);

// Retourner les données encodées en JSON
response = {
  algorithm = 'SHA-256',
  challenge,
  salt,
  signature,
};

Paramètres de Sel

À partir de la version du Widget v0.4 (mai 2024), il est recommandé d’inclure le drapeau expires et des paramètres supplémentaires dans le salt sous forme de chaînes de requête encodées en URL. Cela vous permet de transmettre des données personnalisées, qui feront partie de la signature et pourront être vérifiées sur le serveur.

Le widget détecte automatiquement le paramètre expires lorsqu’il est fourni dans le sel sous forme de timestamp Unix en secondes :

salt = '<random_salt>?expires=1715526540'

Pour assurer la compatibilité avec les futures versions du widget, il est recommandé de préfixer tout paramètre personnalisé avec un trait de soulignement _.

La bibliothèque altcha-lib prend déjà en charge les paramètres de sel et vérifie automatiquement l’expiration du défi à partir de la version v0.3.

Soumission de formulaire

Lors de la soumission dans un élément <form>, le serveur recevra des données encodées en application/x-www-form-urlencoded ou multipart/form-data, selon la structure du formulaire. La charge utile ALTCHA sera incorporée en tant que champ altcha (personnalisable via l’attribut name dans le widget).

Utilisez la valeur du champ altcha comme payload dans les exemples ci-dessous. La charge utile est une chaîne encodée en Base64-JSON.

Validation de la solution

Voici un exemple de pseudo-code pour valider une solution sur le serveur :

// La charge utile est une chaîne encodée BASE64-JSON
// Les données décodées sont un objet contenant { algorithm, challenge, number, salt, signature }
data = json_decode(base64_decode(payload));

// Valider l'algorithme
alg_ok = equals(data.algorithm, 'SHA-256');

// Valider le challenge
challenge_ok = equals(data.challenge, sha2_hex(concat(data.salt, data.number)))

// Valider la signature
signature_ok = equals(data.signature, hmac_sha2_hex(data.challenge, hmac_key))

// Considérer la demande comme vérifiée si toutes les vérifications sont vraies
verified = alg_ok and challenge_ok and signature_ok

Exemple

La bibliothèque JS officielle fonctionne avec Node.js, Bun et Deno.

import { createChallenge, verifySolution } from 'altcha-lib';

const hmacKey = '$ecret.key'; // Changer la clé secrète HMAC

// Créer un nouveau challenge et l'envoyer au client :
const challenge = await createChallenge({
  hmacKey,
});

// Lors de la soumission, vérifiez la charge utile :
const ok = await verifySolution(payload, hmacKey);

Pour plus d’exemples et d’intégrations, consultez la page des Intégrations de la communauté.

Recommandations de sécurité

Attaques de rejeu

Pour prévenir la vulnérabilité des “attaques de rejeu”, où un client soumet la même solution plusieurs fois, le serveur doit mettre en place des mesures qui invalident les défis résolus précédemment.

Le serveur doit maintenir un registre des défis résolus et rejeter toutes les soumissions qui tentent de réutiliser un défi qui a déjà été résolu avec succès.
Expiration du challenge

Limiter la période de validité des défis peut renforcer les mesures de sécurité, assurant que les défis ne peuvent pas être exploités indéfiniment. Mettre en place l’expiration du défi implique de définir une limite de temps dans laquelle un défi doit être résolu et soumis.

Une méthode efficace pour atteindre l’expiration du défi consiste à incorporer un horodatage du serveur dans le salt du défi lors de sa génération.

À partir de la version 0.4 du widget, vous pouvez utiliser les paramètres de sel et inclure le paramètre ?expires=<unix_ts> dans le sel. Le widget détectera automatiquement le paramètre expires. Votre serveur devra alors vérifier l’expiration lors du processus de vérification.