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 enmanifest.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í.
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.manifest.integrity.recipe.
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).
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.- Al sellar, se envía a los calendarios de OpenTimestamps un compromiso de 32 bytes, y la prueba queda
pendingdentro del documento. Se usan los dos calendarios que opera opentimestamps.org. - 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.
- El documento ya entregado no cambia. La prueba completa se descarga aparte, como archivo
.ots, desdeGET /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.ots verify).
La prueba completa
Dos rutas abiertas, sin clave de API y sin créditos:- El estado trae
status(pendingocomplete), los bloques de Bitcoin que anclan la prueba con sumerkle_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:
404si ese servidor no selló esa huella;400si 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ó, enmanifest.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.