TLDR: Integrazione del Server ALTCHA

Questa guida offre una panoramica sintetica sull’integrazione di ALTCHA sul tuo server, coprendo entrambe le modalità: con e senza il filtro dello spam. Seguendo questi passaggi, garantirai una verifica sicura ed efficiente delle sottomissioni degli utenti, che tu abbia bisogno di una verifica di sfida di base o di un filtraggio dello spam avanzato.

Per un’integrazione semplice, considera di utilizzare le librerie ufficiali:

TypeScript

PHP

Go

Python

Java

Ruby

Elixir

Community libraries: C# Clojure Rust

Panoramica della Configurazione

1. Recupero della Sfida:

   • Il lato client recupera una sfida utilizzando il widget ALTCHA.

2. Risoluzione della Sfida:

   • Il lato client risolve la sfida.

3. Invio della Soluzione:

   • Soluzione e dati dell’utente vengono inviati al server.

4. Verifica sul Server:

   • Il server convalida la soluzione e, se utilizza il filtro dello spam, convalida la classificazione dello spam.

Senza Filtro dello Spam

Documentazione completa: Integrazione del Server

Creazione di una Sfida (Lato server)

• Generare Parametri:
  • maxnumber: Numero casuale massimo (aggiusta la difficoltà).
  • salt: Stringa casuale (≥10 caratteri).
  • secret_number: Numero intero casuale (0…maxnumber).
  • challenge: Hash SHA-256 di salt + secret_number.
  • signature: HMAC-SHA-256 di challenge con una chiave segreta.

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

Convalida di una Soluzione (Lato server)

• Decodifica Payload:

  • Estrarre algorithm, challenge, number, salt, signature dal payload Base64-JSON.

• Passaggi di Convalida:

  • alg_ok: Verifica che l’algoritmo sia ‘SHA-256’.
  • challenge_ok: Verifica che challenge corrisponda a sha2_hex(concat(salt, number)).
  • signature_ok: Verifica che signature corrisponda a 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;

Con Filtro dello Spam

Documentazione completa: Integrazione del Server

Uso dell’API con il Widget

• Configurazione del Widget:
  • Imposta challengeurl con la tua chiave API.
  • Abilita spamfilter per la classificazione dello spam.

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

Verifica del Server

• Formato del Payload:
  • Ricevi un oggetto JSON codificato in base64 con le proprietà algorithm, signature, verificationData e verified.

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

Verifica della Firma

1. Calcola l’hash SHA di verificationData.
2. Calcola la firma HMAC usando la parte segreta della tua chiave API.

Esempio pseudo-codice:

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

• Verifica:
  • Il payload è verificato se la firma calcolata corrisponde alla proprietà signature.

Verifica dei Campi (Filtro dello Spam)

• Verifica fields e fieldsHash:
  • Concatenare i valori dei campi con \n e calcolare l’hash SHA.

Esempio pseudo-codice:

hash = sha2_hex(valore_campo1 + "\n" + valore_campo2 + "\n" + valore_campo3);

• Convalida:
  • I dati sono corretti se l’hash calcolato corrisponde a fieldsHash.

Codice di Esempio

• Esempio in Node.js:

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

const hmacKey = '$ecret.key'; // Chiave segreta HMAC

// Crea una nuova sfida
const challenge = await createChallenge({ hmacKey });

// Verifica il payload inviato
const ok = await verifySolution(payload, hmacKey);

Raccomandazioni di Sicurezza

• Prevenire gli Attacchi a Ripetizione:

  • Invalida le sfide risolte in precedenza.

• Scadenza della Sfida:

  • Includi un timestamp nel salt per limitare il periodo di validità.
  • Usa salt = '<random_salt>?expires=<unix_ts>'.

Punti Fine dell’API

• Creazione di una Nuova Sfida:

  • GET /api/v1/challenge

• Verifica della Soluzione:

  • POST /api/v1/challenge/verify

• Convalida della Firma del Server:

  • POST /api/v1/challenge/verify_server_signature