Saltar al contenido principal
Cada documento que emite Blockgence sale sellado. Son paquetes de evidencia, pedidos de congelamiento, post-mortems, entregables de incidentes y pruebas de pago en Monero. El sello tiene tres piezas. Cada una prueba algo distinto, y ninguna prueba que el contenido sea verdadero:
La veracidad de lo que dice un documento la sostienen la metodología publicada, las fuentes que cita y lo que el propio documento declara que no pudo ver. El sello no la reemplaza.

Dónde va el sello

Todo vive en manifest.integrity. La huella cubre todo el documento excepto manifest.integrity: un hash no puede cubrirse a sí mismo. Por eso firma y sello de tiempo van adentro de integrity, en attestations, y no se invalidan entre sí.
Los valores de este ejemplo son ilustrativos.

1. La huella del contenido

Un JSON se puede reordenar o re-indentar sin cambiar su significado, y eso rompería cualquier hash «del archivo». Por eso la huella se calcula sobre una forma canónica publicada, que se puede reproducir sin el código de Blockgence:
1

Quitar la sección de integridad

Tomar el documento completo y quitar manifest.integrity.
2

Serializar en forma canónica

JSON con las claves ordenadas alfabéticamente en todo nivel, separadores , y : sin espacios, y UTF-8 sin escapar.
3

Aplicar sha256

El hex resultante es manifest.integrity.digest. Cualquier alteración del contenido (un monto, una confianza, una fecha) lo cambia.
La receta viaja también dentro de cada documento, en manifest.integrity.recipe.
Límite declarado. Los números con decimales se escriben con la representación más corta que vuelve al mismo valor, que es lo que emiten Python y JavaScript. Otros lenguajes pueden diferir en la notación exponencial (1e-07 frente a 1e-7). Para los valores de un paquete (montos, confianzas, porcentajes) no pasa en la práctica. Si pasara, la referencia son los bytes canónicos del documento.

2. La firma de Blockgence

La huella sola no dice quién emitió el documento. La firma ata esa huella a la clave de Blockgence.
  • Algoritmo: Ed25519 (RFC 8032).
  • Mensaje firmado: los bytes ASCII de blockgence-integrity-v1:sha256: seguidos de la huella en hex. El prefijo fija el algoritmo de la huella y evita que la firma sirva para otra cosa.
  • Dónde está: manifest.integrity.attestations.signature, con:
    • key_id: el sha256 de los 32 bytes de la clave pública;
    • la clave pública, en base64 (public_key) y en PEM (public_key_pem);
    • la firma en base64 (value);
    • la receta para verificarla, incluida una con OpenSSL (verify_openssl).
La clave pública viaja dentro del documento para poder verificar sin pedirla, pero sola no prueba nada: cualquiera puede quitar la firma y firmar con su propia clave. Lo que prueba que lo emitió Blockgence es que su key_id coincida con la clave pública que publicamos.
Quien verifica rehace el mensaje con la huella que recalcula del contenido. Nunca usa la huella ni el mensaje que trae el documento: integrity no está cubierto por la huella y cualquiera puede editarlo. Si el servidor que emitió el documento no tenía una clave de firma configurada, signature sale null y signature_note dice por qué. En ese caso la huella prueba que el documento no cambió, pero no quién lo emitió.

3. El sello de tiempo (opcional)

La firma no prueba cuándo se emitió un documento: manifest.generated_at lo pone el propio sistema. El sello de tiempo ancla la huella en Bitcoin con OpenTimestamps.
El sello de tiempo está apagado por defecto: lo enciende el operador del servidor. Cuando no está, el documento sale igual, con timestamp: null y una nota en timestamp_note. Tampoco se sellan los documentos hechos con datos simulados.
Cuando está encendido:
  1. Al sellar, se envía a los calendarios de OpenTimestamps un compromiso de 32 bytes, y la prueba queda pending dentro del documento. Se usan los dos calendarios que opera opentimestamps.org.
  2. Unas horas después, los calendarios incluyen el compromiso en una transacción de Bitcoin. El servidor completa la prueba solo, una vez por hora.
  3. El documento ya entregado no cambia. La prueba completa se descarga aparte, como archivo .ots, desde GET /v1/evidence/timestamp/{digest}.ots.
Qué sale de la máquina. A cada calendario se le manda un único pedido de 32 bytes: sha256(huella || nonce), con un nonce de 16 bytes al azar que queda en la prueba y nunca se envía. No sale el contenido, ni la huella misma, ni datos del caso.
Lo que prueba, cuando se completa: que la huella del documento ya existía cuando se minó el bloque de Bitcoin que cita la prueba. Mientras la prueba esté pendiente, no prueba nada todavía: solo registra que se pidió el sello. Las pruebas que produce Blockgence las lee y verifica el cliente oficial de OpenTimestamps (ots verify).

La prueba completa

Dos rutas abiertas, sin clave de API y sin créditos:
  • El estado trae status (pending o complete), los bloques de Bitcoin que anclan la prueba con su merkle_root, los calendarios, las fechas y cómo verificar.
  • El archivo viene con el header X-OTS-Status.
  • Mientras sigue pendiente, cada pedido intenta completarla, como mucho una vez cada 10 minutos por huella.
  • Errores: 404 si ese servidor no selló esa huella; 400 si el nombre no es un sha256 en hex.

Qué versión de la metodología

Cada documento cita la metodología con que se armó, en manifest.methodology: su versión (version), una huella de sus parámetros reales (fingerprint) y cuántas entradas tiene. El paquete trae además las entradas que usó ese análisis. Ver Changelog de metodología.

Siguiente paso

Verificar una firma

Paso a paso, con Python 3 y OpenSSL, sin cuenta y sin el código de Blockgence.

Clave pública

La huella vigente, dónde se publica y qué pasa si cambia.