Zusammenfassung: ALTCHA Serverintegration

Diese Anleitung bietet einen knappen Überblick über die Integration von ALTCHA auf Ihrem Server und umfasst beide Modi: mit und ohne Spamfilter. Durch Befolgen dieser Schritte stellen Sie eine sichere und effiziente Überprüfung von Benutzereingaben sicher, egal ob Sie eine grundlegende Herausforderungsprüfung oder eine erweiterte Spamfilterung benötigen.

Für eine einfache Integration empfehlen wir die Verwendung der offiziellen Bibliotheken:

TypeScript

PHP

Go

Python

Java

Ruby

Elixir

Community libraries: C# Clojure Rust

Setup-Übersicht

1. Abrufen der Herausforderung:

   • Der Client lädt eine Herausforderung mithilfe des ALTCHA-Widgets herunter.

2. Herausforderung lösen:

   • Der Client löst die Herausforderung.

3. Lösung übermitteln:

   • Lösung und Benutzerdaten werden an den Server übermittelt.

4. Überprüfung auf dem Server:

   • Der Server validiert die Lösung und überprüft bei Verwendung des Spamfilters die Spamklassifizierung.

Ohne Spamfilter

Vollständige Dokumentation: Serverintegration

Erstellen einer Herausforderung (Serverseitig)

• Parameter generieren:
  • maxnumber: Maximale Zufallszahl (passt die Schwierigkeit an).
  • salt: Zufälliger String (≥10 Zeichen).
  • secret_number: Zufällige Ganzzahl (0…maxnumber).
  • challenge: SHA-256-Hash von salt + secret_number.
  • signature: HMAC-SHA-256 von challenge mit einem geheimen Schlüssel.

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,
};

Lösung validieren (Serverseitig)

• Payload entschlüsseln:

  • Extrahieren Sie algorithm, challenge, concat, salt, signature aus Base64-JSON-Payload.

• Validierungsschritte:

  • alg_ok: Prüfen, ob der Algorithmus ‘SHA-256’ ist.
  • challenge_ok: Überprüfen, ob challenge mit sha2_hex(concat(salt, concat)) übereinstimmt.
  • signature_ok: Überprüfen, ob signature mit hmac_sha2_hex(challenge, hmac_key) übereinstimmt.

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;

Mit Spamfilter

Vollständige Dokumentation: Serverintegration

Verwendung der API mit dem Widget

• Widget-Konfiguration:
  • Setzen Sie challengeurl mit Ihrem API-Schlüssel.
  • Aktivieren Sie spamfilter für die Spamklassifizierung.

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

Serververifizierung

• Payload-Format:
  • Sie erhalten ein Base64-codiertes JSON-Objekt mit den Eigenschaften algorithm, signature, verificationData und verified.

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

Überprüfen der Signatur

1. Berechnen Sie den SHA-Hash von verificationData.
2. Berechnen Sie die HMAC-Signatur mit dem geheimen Teil Ihres API-Schlüssels.

Beispiel-Pseudocode:

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

• Überprüfung:
  • Der Payload wird überprüft, wenn die berechnete Signatur mit der signature-Eigenschaft übereinstimmt.

Überprüfen von Feldern (Spamfilter)

• Überprüfen von fields und fieldsHash:
  • Verketten Sie Feldwerte mit \n und berechnen Sie den SHA-Hash.

Beispiel-Pseudocode:

hash = sha2_hex(feld1_wert + "\n" + feld2_wert + "\n" + feld3_wert);

• Validierung:
  • Die Daten sind korrekt, wenn der berechnete Hash mit dem fieldsHash übereinstimmt.

Beispielcode

• Node.js Beispiel:

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

const hmacKey = '$ecret.key'; // Geheimer HMAC-Schlüssel

// Erstellen einer neuen Herausforderung
const challenge = await createChallenge({ hmacKey });

// Überprüfen des übermittelten Payloads
const ok = await verifySolution(payload, hmacKey);

Sicherheitsempfehlungen

• Wiederholungsangriffe verhindern:

  • Ungültige gelöste Herausforderungen.

• Ablauf der Herausforderung:

  • Fügen Sie einen Zeitstempel in das salt ein, um die Gültigkeitsdauer zu begrenzen.
  • Verwenden Sie salt = '<zufälliger_salt>?abläuft=<unix_ts>'.

API-Endpunkte

• Erstellen einer neuen Herausforderung:

  • GET /api/v1/challenge

• Lösung überprüfen:

  • POST /api/v1/challenge/verify

• Validieren der Server-Signatur:

  • POST /api/v1/challenge/verify_server_signature