TLDR: Integración del Servidor ALTCHA

Esta guía ofrece una descripción concisa de cómo integrar ALTCHA en tu servidor, cubriendo ambos modos: con y sin el filtro de spam. Siguiendo estos pasos, garantizarás una verificación segura y eficiente de las presentaciones de los usuarios, ya sea que necesites verificación básica de desafíos o filtrado avanzado de spam.

Para una integración fácil, considera usar las bibliotecas oficiales:

TypeScript

PHP

Go

Python

Java

Ruby

Elixir

Community libraries: C# Clojure Rust

Resumen de Configuración

1. Obtener Desafío:

   • El cliente obtiene un desafío usando el widget de ALTCHA.

2. Resolver Desafío:

   • El cliente resuelve el desafío.

3. Enviar Solución:

   • La solución y los datos del usuario se envían al servidor.

4. Verificar en el Servidor:

   • El servidor valida la solución y, si se utiliza el filtro de spam, valida la clasificación del spam.

Sin Filtro de Spam

Documentación completa: Integración del Servidor

Creación de un Desafío (Lado del Servidor)

• Generar Parámetros:
  • maxnumber: Número aleatorio máximo (ajusta la dificultad).
  • salt: Cadena aleatoria (≥10 caracteres).
  • secret_number: Entero aleatorio (0…maxnumber).
  • challenge: Hash SHA-256 de salt + secret_number.
  • signature: HMAC-SHA-256 de challenge con una clave secreta.

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

Validación de una Solución (Lado del Servidor)

• Decodificar Carga:

  • Extraer algorithm, challenge, number, salt, signature de la carga Base64-JSON.

• Pasos de Validación:

  • alg_ok: Verificar que el algoritmo sea ‘SHA-256’.
  • challenge_ok: Verificar que challenge coincida con sha2_hex(concat(salt, number)).
  • signature_ok: Verificar que signature coincida con 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 de Spam

Documentación completa: Integración del Servidor

Usar la API con el Widget

• Configuración del Widget:
  • Establecer challengeurl con tu clave API.
  • Habilitar spamfilter para clasificación de spam.

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

Verificación del Servidor

• Formato de Carga:
  • Recibes un objeto JSON codificado en base64 con las propiedades algoritmo, signature, verificationData y verified.

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

Verificar la Firma

1. Calcular el hash SHA de verificationData.
2. Calcular la firma HMAC usando la parte secreta de tu clave API.

Ejemplo de pseudocódigo:

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

• Verificación:
  • La carga se verifica si la firma calculada coincide con la propiedad signature.

Verificar Campos (Filtro de Spam)

• Verificar fields y fieldsHash:
  • Concatenar valores de campos con \n y calcular el hash SHA.

Ejemplo de pseudocódigo:

hash = sha2_hex(valor_campo1 + "\n" + valor_campo2 + "\n" + valor_campo3);

• Validación:
  • Los datos son correctos si el hash calculado coincide con fieldsHash.

Código de Ejemplo

• Ejemplo Node.js:

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

const hmacKey = '$ecret.key'; // Clave secreta HMAC

// Crear un nuevo desafío
const challenge = await createChallenge({ hmacKey });

// Verificar la carga enviada
const ok = await verifySolution(payload, hmacKey);

Recomendaciones de Seguridad

• Prevenir Ataques de Repetición:

  • Invalidar desafíos previamente resueltos.

• Caducidad de Desafíos:

  • Incluir una marca de tiempo en el salt para limitar el período de validez.
  • Utilizar salt = '<salt_aleatorio>?expires=<unix_ts>'.

Puntos Fin de API

• Crear un Nuevo Desafío:

  • GET /api/v1/challenge

• Verificar Solución:

  • POST /api/v1/challenge/verify

• Validar Firma del Servidor:

  • POST /api/v1/challenge/verify_server_signature