TLDR : Intégration du serveur ALTCHA

Ce guide offre un aperçu succinct de l’intégration d’ALTCHA sur votre serveur, couvrant les deux modes : avec et sans le filtre anti-spam. En suivant ces étapes, vous assurerez une vérification sécurisée et efficace des soumissions des utilisateurs, que vous ayez besoin d’une vérification de défi de base ou d’un filtrage avancé des spams.

Pour une intégration facile, envisagez d’utiliser les bibliothèques officielles:

TypeScript

PHP

Go

Python

Java

Ruby

Elixir

Community libraries: C# Clojure Rust

Aperçu de la configuration

1. Récupérer le défi:

   • Le côté client récupère un défi en utilisant le widget ALTCHA.

2. Résoudre le défi:

   • Le côté client résout le défi.

3. Soumettre la solution:

   • La solution et les données de l’utilisateur sont soumises au serveur.

4. Vérifier sur le serveur:

   • Le serveur valide la solution et, s’il utilise le filtre anti-spam, valide la classification du spam.

Sans filtre anti-spam

Documentation complète : Intégration du serveur

Création d’un défi (Côté serveur)

• Générer les paramètres:
  • maxnumber : Nombre aléatoire maximum (ajuste la difficulté).
  • salt : Chaîne aléatoire (≥10 caractères).
  • secret_number : Entier aléatoire (0…maxnumber).
  • challenge : Hash SHA-256 de salt + secret_number.
  • signature : HMAC-SHA-256 de challenge avec une clé secrète.

maxnumber = 100_000;
salt = random_string();
secret_number = random_int(maxnumber);
challenge = sha2_hex(concat(salt, secret_number));
signature = hmac_sha2_hex(challenge, hmac_key);
response = {
  algorithm: 'SHA-256',
  challenge,
  maxnumber,
  salt,
  signature,
};

Validation d’une solution (Côté serveur)

• Décoder la charge utile:

  • Extraire algorithm, challenge, number, salt, signature de la charge utile Base64-JSON.

• Étapes de validation:

  • alg_ok : Vérifier que l’algorithme est ‘SHA-256’.
  • challenge_ok : Vérifier que challenge correspond à sha2_hex(concat(salt, number)).
  • signature_ok : Vérifier que signature correspond à hmac_sha2_hex(challenge, hmac_key).

data = json_decode(base64_decode(payload));
alg_ok = equals(data.algorithm, 'SHA-256');
challenge_ok = equals(data.challenge, sha2_hex(concat(data.salt, data.number)));
signature_ok = equals(data.signature, hmac_sha2_hex(data.challenge, hmac_key));
verified = alg_ok && challenge_ok && signature_ok;

Avec filtre anti-spam

Documentation complète : Intégration du serveur

Utilisation de l’API avec le Widget

• Configuration du Widget:
  • Définissez challengeurl avec votre clé API.
  • Activez spamfilter pour la classification du spam.

<altcha-widget
  challengeurl="https://eu.altcha.org/api/v1/challenge?apiKey=ckey_..."
  spamfilter
></altcha-widget>

Vérification du serveur

• Format de la charge utile:
  • Vous recevez un objet JSON encodé en base64 avec les propriétés algorithm, signature, verificationData et verified.

{
  "algorithm": "SHA-256",
  "signature": "71b86949a1a84595f71d8abd7bdef414e8b883247e30cba93f4946b028c4fbf1",
  "verificationData": "classification=BAD&score=7.75&...&time=1713566250&verified=true",
  "verified": true
}

Vérification de la signature

1. Calculer le hash SHA de verificationData.
2. Calculer la signature HMAC en utilisant la partie secrète de votre clé API.

Exemple de pseudo-code :

hash = sha2(payload.verificationData);
signature = hmac_sha2_hex(hash, hmac_key);

• Vérification:
  • La charge utile est vérifiée si la signature calculée correspond à la propriété signature.

Vérification des champs (Filtre anti-spam)

• Vérifier les champs et fieldsHash:
  • Concaténer les valeurs des champs avec \n et calculer le hash SHA.

Exemple de pseudo-code :

hash = sha2_hex(field1_value + "\n" + field2_value + "\n" + field3_value);

• Validation:
  • Les données sont correctes si le hash calculé correspond à fieldsHash.

Exemple de code

• Exemple Node.js :

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

const hmacKey = '$ecret.key'; // Clé HMAC secrète

// Créer un nouveau défi
const challenge = await createChallenge({ hmacKey });

// Vérifier la charge utile soumise
const ok = await verifySolution(payload, hmacKey);

Recommandations de sécurité

• Prévenir les attaques de rejeu:

  • Invalider les défis déjà résolus.

• Expiration du défi:

  • Inclure un horodatage dans le salt pour limiter la période de validité.
  • Utiliser salt = '<random_salt>?expires=<unix_ts>'.

Points de terminaison de l’API

• Créer un nouveau défi :

  • GET /api/v1/challenge

• Vérifier la solution:

  • POST /api/v1/challenge/verify

• Valider la signature du serveur:

  • POST /api/v1/challenge/verify_server_signature

Pour plus de détails, consultez la documentation officielle.