PoW-Herausforderungen API

Nutzen Sie die Challenge-API in Verbindung mit dem ALTCHA-Widget, um kryptografische Herausforderungen zu generieren und zu validieren.

Die API bietet mehrere Vorteile gegenüber der selbst gehosteten Challenge-Verifizierung:

• Vereinfachte Integration mit beliebigen Backends oder CMS.
• Zusätzliche Sicherheitsmaßnahmen wie Ablauf der Herausforderung und Schutz vor Wiederverwendung.
• Möglichkeit, den Spam-Filter direkt aus dem Widget zu nutzen, um eine Datenklassifizierung vor der Übermittlung an Ihren Server durchzuführen.
• Keine API-Anfragen von Ihrem Server aus; alles wird kryptografisch überprüft, was die Latenz reduziert und mögliche Netzwerkprobleme beseitigt.

Autorisierung

Der Zugriff auf die API erfordert einen API-Schlüssel. Siehe API-Autorisierung.

Verwendung mit dem Widget

Um die API mit dem Widget von ALTCHA zu nutzen, konfigurieren Sie die challengeurl und denken Sie daran, Ihren API-Schlüssel in der URL einzuschließen:

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

Tipp

ALTCHA SaaS ist in zwei Regionen verfügbar: eu.altcha.org und us.altcha.org. Wählen Sie die Region, die am besten zu Ihren Anforderungen passt.

Spam-Filter aktivieren

Die API ermöglicht auch eine automatische Datenklassifizierung für Spam unter Verwendung des Spam-Filters. Um den Spam-Filter zu aktivieren, fügen Sie dem Widget das Attribut spamfilter hinzu (erfordert Version 0.3+):

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

Mit aktiviertem Spam-Filter wird die Verifizierung automatisch Textfelder aus dem Formular zusammen mit erkannten E-Mail-Adressen übermitteln und ein Klassifizierungsergebnis zurückgeben.

Um die Klassifizierung auf Ihrer Website zu verarbeiten, nutzen Sie das serververification Event des Widgets. Eine eingeschränkte Version der Klassifizierung ist auch im neuen payload enthalten, der an Ihren Server übermittelt wird.

Wichtig

Die Verwendung der ALTCHA-API als challengeurl zusammen mit spamfilter verändert den Verifizierungsprozess auf dem Server. Bitte beachten Sie Server-Verifizierung.

Server-Verifizierung

Bei Verwendung der ALTCHA-API mit spamfilter hat der payload, der auf Ihrem Server empfangen wurde, ein anderes Format als der vom Widget generierte Payload.

Sie erhalten einen Base64-codierten String, der ein JSON-codiertes Objekt enthält:

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

Payload-Eigenschaften:

• algorithm - Der für die HMAC-Signatur verwendete Algorithmus.
• signature HMAC-Signatur der verificationData.
• verificationData - URL-codierte Verifizierungs- und Klassifizierungsdaten.
  • time - Zeitstempel der Verifizierung in Sekunden.
  • verified - Ob die Lösung erfolgreich verifiziert wurde.
  • Bei aktiviertem spamfilter (siehe Spam-Filter Antwort):
    • classification - Klassifizierung des Spam-Filters.
    • expire - Ablaufzeit in Sekunden.
    • email - Übermittelte E-Mail.
    • fields - Array von Feldnamen, die übermittelt wurden.
    • fieldsHash - SHA-Hash der Feldwerte.
    • ipAddress - Die IP-Adresse des Benutzers.
    • reasons - Array von Gründen.
    • score - Gesamtklassifizierungspunkt.
• verified - Ob die Lösung erfolgreich verifiziert wurde.

Verifizierung der Signatur

Um zu überprüfen, ob der Client verifiziert wurde, prüfen Sie die im Payload empfangene Signatur:

1. Berechnen Sie einen SHA-Hash der verificationData (unter Verwendung des algorithm).
2. Berechnen Sie eine HMAC-Signatur mit dem gleichen algorithm, wobei der hmac_key der geheime Teil Ihres API-Schlüssels ist (d.h. csec_...).

Beispiel-Pseudocode mit dem Algorithmus SHA-256:

// Berechnen Sie den SHA-Hash der `verificationData`, ungeparst, wie sie im Payload erscheinen (der Hash enthält rohe Binärdaten, NICHT hex-kodiert):
hash = sha2(payload.verificationData);

// Berechnen Sie die HMAC-Signatur
signature = hmac_sha2_hex(hash, hmac_key);

Der Payload gilt als verifiziert, wenn die berechnete Signatur mit der Eigenschaft signature der Nutzlast übereinstimmt. Es wird auch empfohlen, die übermittelten Daten gemäß dem Abschnitt Überprüfung von Feldern unten zu überprüfen.

Alternativ, falls Sie die Signatur nicht kryptografisch überprüfen können, nutzen Sie den Server-Signatur-Verifizierungs-Endpunkt.

Überprüfung von Feldern

Wenn Sie den Spam-Filter verwenden, enthält verificationData zusätzliche Eigenschaften: fields und fieldsHash. Diese Eigenschaften ermöglichen es Ihnen, die Genauigkeit der klassifizierten Daten zu validieren. Dieser Überprüfungsschritt stellt sicher, dass der Benutzer die übermittelten Daten seit deren Validierung durch den Spam-Filter nicht geändert hat.

Um den Felder-Hash zu überprüfen, konkatenieren Sie die Werte der Felder mit \n (neue Zeile) und berechnen Sie den SHA-Hash (unter Verwendung des angegebenen algorithm). Wenn zum Beispiel fields = field1,field2,field3:

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

Stellen Sie sicher, dass die Werte in der Reihenfolge sortiert sind, in der sie in der Eigenschaft fields erscheinen.

Die Daten gelten als korrekt, wenn der berechnete Hash mit dem fieldsHash übereinstimmt.

API-Endpunkte

Wenn Sie die API direkt ohne das Widget verwenden möchten, nutzen Sie die folgenden Endpunkte. Denken Sie daran, dass der Referer-Header immer vorhanden sein muss und die Herkunft (Domain) Ihrer Website enthalten muss.

Neue Herausforderung erstellen

• GET /api/v1/challenge
• API-Referenz

Lösung überprüfen

• POST /api/v1/challenge/verify
• API-Referenz

Server-Signatur validieren

Dieser Endpunkt dient als alternative Möglichkeit zur Verifizierung der Server-Signatur, die von /api/v1/challenge/verify empfangen wurde. Eine kryptografische Verifizierung wird empfohlen.

• POST /api/v1/challenge/verify_server_signature
• API-Referenz