> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificar una firma

> Comprobar, sin cuenta y sin el código de Blockgence, que un documento no cambió y que lo emitió Blockgence: con Python 3 y OpenSSL 3.

Con esta guía se comprueba que un documento sellado de Blockgence **no cambió** y que **lo emitió Blockgence**. No hace falta cuenta ni el código de Blockgence: solo Python 3 y OpenSSL 3.

> [!NOTE]
>
> **Qué necesitás**
>
> * El documento, en JSON (por ejemplo `documento.json`).
> * Python 3, sin instalar nada más.
> * OpenSSL 3.0 o posterior. El `/usr/bin/openssl` de macOS es LibreSSL y no lee claves Ed25519: usá el de Homebrew (`brew install openssl@3`).
> * La [clave pública de Blockgence](https://docs.blockgence.com/es/methodology/public-key.md), guardada como `blockgence-evidencia.pub.pem`.

**1. Recalcular la huella del contenido**

Quitá `manifest.integrity`, ordená las claves, serializá sin espacios en UTF-8 y aplicá sha256:

```bash theme={null}
python3 -c 'import hashlib,json,sys; d=json.load(open(sys.argv[1],encoding="utf-8")); d["manifest"].pop("integrity"); print(hashlib.sha256(json.dumps(d,sort_keys=True,separators=(",",":"),ensure_ascii=False).encode()).hexdigest())' documento.json
```

Tiene que dar lo mismo que `manifest.integrity.digest`. **Si no coincide, el documento cambió** y no hace falta seguir.

**2. Armar el mensaje firmado**

El mensaje es el texto `blockgence-integrity-v1:sha256:` seguido de la huella que calculaste en el paso 1. Usá siempre la huella recalculada, nunca la que trae el documento.

```bash theme={null}
printf '%s' 'blockgence-integrity-v1:sha256:<huella del paso 1>' > msg.txt
```

**3. Extraer la firma**

La firma es el campo `value` de `manifest.integrity.attestations.signature`, en base64:

```bash theme={null}
printf '%s' '<value>' | openssl base64 -d -A > sig.bin
```

**4. Verificar con la clave publicada**

Verificá con la clave bajada de la [página de la clave pública](https://docs.blockgence.com/es/methodology/public-key.md), no con la que trae el documento:

```bash theme={null}
openssl pkeyutl -verify -pubin -inkey blockgence-evidencia.pub.pem -rawin -in msg.txt -sigfile sig.bin
```

Tiene que responder `Signature Verified Successfully`. Como se verifica con la clave publicada, una firma hecha con otra clave falla acá.

**5. Opcional: comparar la huella de la clave del documento**

Guardá el `public_key_pem` del documento en `pub.pem`. Esto tiene que dar el `key_id` publicado:

```bash theme={null}
openssl pkey -pubin -in pub.pem -outform DER | tail -c 32 | openssl dgst -sha256
```

El resultado se compara con el hex de `sha256:d8853d1c1b7322b8b7e3bab730fccd0652c0c97a825c3317b3bc705d650f5c5f`.

Cada documento trae además la receta completa: la de la huella en `manifest.integrity.recipe` y la de la firma con OpenSSL en `attestations.signature.verify_openssl`.

## Qué significa cada resultado

| Resultado | Qué quiere decir |
| - | - |
| La huella no coincide (paso 1) | El documento cambió después de sellarse. |
| `Signature Verified Successfully` (paso 4) | Lo emitió quien tiene la clave privada de Blockgence y no cambió desde que se firmó. |
| La verificación falla con la clave publicada | La firma no es de Blockgence, o el documento se alteró y se le recalculó la huella. |
| `signature` es `null` | El documento no trae firma: no prueba quién lo emitió. `signature_note` dice por qué, pero esa nota no está cubierta por la huella, así que es solo informativa. |
| El `key_id` es de una clave retirada | Vale si el documento es del período de esa clave. |
| El `key_id` es de una clave revocada | No se confía en el documento, tampoco si está fechado antes de la revocación. |

## Qué prueba la firma y qué no

> [accordion] Prueba
>
> Que el documento lo emitió quien tiene la clave privada de Blockgence y que no cambió desde que se firmó.

> [accordion] No prueba que el contenido sea verdadero o completo
>
> Eso lo sostienen la metodología, las fuentes y lo que el propio documento declara que no pudo ver.

> [accordion] No prueba la hora
>
> `manifest.generated_at` lo pone el propio sistema y no lo certifica un tercero. Una cota la da el sello de tiempo, si el documento lo trae.

## Verificar el sello de tiempo

Si el documento trae `attestations.timestamp`, la huella se puede anclar en Bitcoin con el cliente oficial de [OpenTimestamps](https://opentimestamps.org). El sello está apagado por defecto: muchos documentos no lo traen, y lo dicen en `timestamp_note`.

**1. Bajar la prueba completa**

La prueba que trae el documento es la pendiente, porque el documento no cambia después de emitirse. Esperá la confirmación en Bitcoin (unas horas) y bajá la completa del enlace `complete_proof_url`, o de `GET /v1/evidence/timestamp/{digest}.ots`.

**2. Verificar con el cliente oficial**

Con la huella recalculada en el paso 1 de arriba:

```bash theme={null}
ots verify -d <huella recalculada> <huella>.ots
```

Necesita un nodo de Bitcoin, aunque sea podado.

**3. Sin nodo de Bitcoin**

`ots info <huella>.ots` muestra el bloque y la raíz de Merkle. Esa raíz se compara con la cabecera del bloque en cualquier explorador. La prueba arranca en la huella: `ots info` muestra `File sha256 hash: <huella>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.