Aller au contenu
ALTCHA ALTCHA ALTCHA

API de Défis PoW

Utilisez l’API de Défis en conjonction avec le Widget ALTCHA pour générer et valider des défis cryptographiques.

L’API offre plusieurs avantages par rapport à la vérification de défis auto-hébergée:

  • Intégration simplifiée avec n’importe quel back-end ou CMS.
  • Mesures de sécurité supplémentaires telles que l’expiration des défis et la protection contre la réutilisation.
  • Possibilité d’utiliser le Filtre Anti-Spam directement depuis le widget, permettant la classification des données avant leur soumission à votre serveur.
  • Aucune demande d’API n’est émise depuis votre serveur ; tout est vérifié de manière cryptographique, réduisant la latence et éliminant les problèmes potentiels liés au réseau.

Autorisation

L’accès à l’API nécessite une Clé API. Consultez l’autorisation de l’API.

Utilisation avec le Widget

Pour utiliser l’API avec le widget ALTCHA, configurez l’attribut challengeurl et n’oubliez pas d’inclure votre clé API dans l’URL :

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

Activer le Filtre Anti-Spam

L’API permet également la classification automatique des données pour le spam en utilisant le Filtre Anti-Spam. Pour activer le Filtre Anti-Spam, ajoutez l’attribut spamfilter au widget (nécessite la version 0.3+):

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

Avec le Filtre Anti-Spam activé, la vérification soumettra automatiquement les champs textuels du formulaire ainsi que les adresses e-mail détectées et renverra un résultat de classification.

Pour traiter la classification sur votre site web, utilisez l’événement serververification du widget. Une version limitée de la classification est également incluse dans le nouveau payload soumis à votre serveur.

Important

Utiliser l’API d’ALTCHA en tant que challengeurl avec spamfilter modifie le processus de vérification sur le serveur. Veuillez vous référer à la vérification du serveur.

Vérification du Serveur

Lors de l’utilisation de l’API d’ALTCHA avec spamfilter, le payload reçu sur votre serveur a un format différent de celui généré par le widget.

Vous recevrez une chaîne encodée en base64 contenant un objet encodé en JSON :

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

Propriétés du payload :

  • algorithm - L’algorithme utilisé pour la signature HMAC.
  • signature Signature HMAC des verificationData.
  • verificationData - Données de vérification et classification encodées en URL.
    • time - Horodatage de la vérification en secondes.
    • verified - Si la solution a été vérifiée avec succès.
    • Avec spamfilter activé (voir Réponse du Filtre Anti-Spam):
      • classification - Classification du Filtre Anti-Spam.
      • email - E-mail soumis.
      • expire - Durée d’expiration en secondes.
      • fields - Tableau de noms de champ soumis.
      • fieldsHash - Hash SHA des valeurs de champ.
      • ipAddress - L’adresse IP de l’utilisateur.
      • reasons - Tableau de raisons.
      • score - Score de classification global.
  • verified - Si la solution a été vérifiée avec succès.

Vérification de la Signature

Pour vérifier que le client a été vérifié, vérifiez la signature reçue dans le payload :

  1. Calculez un hash SHA des verificationData (en utilisant l’algorithm).
  2. Calculez une signature HMAC avec le même algorithm, où la hmac_key est la partie secrète de votre clé API (c’est-à-dire csec_...).

Exemple de pseudo-code utilisant l’algorithme SHA-256 :

// calculer le hash SHA des `verificationData`, telles quelles apparaissent dans le payload :
hash = sha2_hex(payload.verificationData);


// calculer la signature HMAC
signature = hmac_sha2_hex(hash, hmac_key);

Le payload est considéré comme vérifié si la signature calculée est égale à la propriété signature du payload. Il est également conseillé de vérifier les données soumises, comme indiqué dans la section Vérification des Champs ci-dessous.

Alternativement, si vous ne pouvez pas vérifier la signature de manière cryptographique, utilisez l’endpoint de vérification de la signature du serveur.

Vérification des Champs

Si vous utilisez le Filtre Anti-Spam, verificationData inclura des propriétés supplémentaires : fields et fieldsHash. Ces propriétés vous permettent de valider l’exactitude des données classées. Cette étape de vérification garantit que l’utilisateur n’a pas altéré les données soumises depuis leur validation par le Filtre Anti-Spam.

Pour vérifier le hash des champs, concaténez les valeurs des champs avec \n (nouvelle ligne) et calculez le hash SHA (en utilisant l’algorithm spécifié). Par exemple, si fields = field1,field2,field3 :

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

Assurez-vous que les valeurs sont triées dans l’ordre où elles apparaissent dans la propriété fields.

Les données sont considérées comme correctes si le hash calculé correspond au fieldsHash.

Points de Terminaison de l’API

Si vous préférez utiliser l’API directement, sans le widget, utilisez les points de terminaison suivants. N’oubliez pas que l’en-tête Referer doit toujours être présent et doit contenir l’origine (domaine) de votre site web.

Création d’un Nouveau Défi

Vérification de la Solution

Validation de la Signature du Serveur

Cet endpoint sert de manière alternative à la vérification de la signature du serveur reçue depuis /api/v1/challenge/verify. La vérification cryptographique est recommandée.