Salta ai contenuti
ALTCHA ALTCHA ALTCHA

API Sfide PoW

Utilizzare l’API delle Sfide in combinazione con il Widget ALTCHA per generare e convalidare sfide crittografiche.

L’API offre diversi vantaggi rispetto alla verifica delle sfide auto-ospitata:

  • Integrazione semplificata con qualsiasi backend o CMS.
  • Misure di sicurezza aggiuntive come la scadenza della sfida e la protezione dal riutilizzo.
  • Possibilità di utilizzare il Filtro antispam direttamente dal widget, consentendo la classificazione dei dati prima dell’invio al server.
  • Zero richieste API effettuate dal tuo server; tutto è verificato crittograficamente, riducendo la latenza ed eliminando potenziali problemi di rete.

Autorizzazione

L’accesso all’API richiede una Chiave API. Fare riferimento all’autorizzazione API.

Utilizzo con il Widget

Per utilizzare l’API con il widget ALTCHA, configurare il challengeurl e ricordarsi di includere la tua Chiave API nell’URL:

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

Abilita il Filtro antispam

L’API consente anche la classificazione automatica dei dati per lo spam utilizzando il Filtro antispam. Per abilitare il Filtro antispam, aggiungere l’attributo spamfilter al widget (richiede la versione 0.3+):

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

Con il Filtro antispam abilitato, la verifica invierà automaticamente i campi di testo del modulo insieme agli indirizzi email rilevati e restituirà un risultato di classificazione.

Per elaborare la classificazione sul tuo sito web, utilizza l’evento serververification del widget. Una versione limitata della classificazione è inclusa anche nel nuovo payload inviato al tuo server.

Importante

Utilizzare l’API di ALTCHA come challengeurl insieme a spamfilter altera il processo di verifica sul server. Fare riferimento alla verifica server.

Verifica Server

Quando si utilizza l’API di ALTCHA con spamfilter, il payload ricevuto sul tuo server ha un formato diverso rispetto al payload generato dal widget.

Riceverai una stringa codificata in base64 contenente un oggetto codificato in JSON:

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

Proprietà del payload:

  • algorithm - L’algoritmo utilizzato per la firma HMAC.
  • signature Firma HMAC dei verificationData.
  • verificationData - Dati di verifica e classificazione codificati in URL.
    • time - Timestamp della verifica in secondi.
    • verified - Se la soluzione è stata verificata con successo.
    • Con spamfilter abilitato (vedi risposta Filtro antispam):
      • classification - Classificazione del Filtro antispam.
      • email - Email inviata.
      • expire - Tempo di scadenza in secondi.
      • fields - Array dei nomi dei campi inviati.
      • fieldsHash - Hash SHA dei valori dei campi.
      • ipAddress - L’indirizzo IP dell’utente.
      • reasons - Array di motivi.
      • score - Punteggio complessivo della classificazione.
  • verified - Se la soluzione è stata verificata con successo.

Verifica della Firma

Per verificare che il client sia stato verificato, controllare la firma ricevuta nel payload:

  1. Calcolare un hash SHA dei verificationData (usando l’algorithm).
  2. Calcolare una firma HMAC con lo stesso algorithm, dove il hmac_key è la parte segreta della tua Chiave API (cioè csec_...).

Esempio pseudo-codice utilizzando l’algoritmo SHA-256:

// calcola l'hash SHA dei `verificationData`, non elaborati, così come appaiono nel payload:
hash = sha2_hex(payload.verificationData);


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

Il payload è considerato verificato se la firma calcolata è uguale alla proprietà signature del payload. È anche consigliabile verificare i dati inviati, come descritto nella sezione Verifica dei Campi di seguito.

In alternativa, se non puoi verificare la firma criptograficamente, utilizza il endpoint di verifica della firma server.

Verifica dei Campi

Se si utilizza il Filtro Antispam, verificationData includerà proprietà aggiuntive: fields e fieldsHash. Queste proprietà consentono di convalidare l’accuratezza dei dati classificati. Questo passaggio di verifica garantisce che l’utente non abbia modificato i dati inviati dalla loro validazione tramite il Filtro Antispam.

Per verificare l’hash dei campi, concatenare i valori dei campi con \n (nuova riga) e calcolare l’hash SHA (utilizzando l’algorithm specificato). Ad esempio, se fields = field1,field2,field3:

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

Assicurarsi che i valori siano ordinati nell’ordine in cui appaiono nella proprietà fields.

I dati sono considerati corretti se l’hash calcolato corrisponde al fieldsHash.

Endpoint API

Se preferisci utilizzare direttamente l’API, senza il widget, utilizza i seguenti endpoint. Ricorda che l’intestazione Referer deve essere sempre presente e deve contenere l’origine (dominio) del tuo sito web.

Creazione di una Nuova Sfida

Verifica Soluzione

Convalida Firma Server

Questo endpoint funge da modo alternativo per verificare la firma del server ricevuta da /api/v1/challenge/verify. Si consiglia la verifica crittografica.