Saltar a contenido

Verificador de atestaciones

Una atestación de HodeiShield es un documento firmado que un cliente, auditor o regulador puede verificar sin conexión — sin cuenta de HodeiShield, sin ninguna llamada de red hacia nosotros en el momento de verificar. La firma prueba que el titular de una clave firmó el documento; no prueba que esa clave pertenezca a la organización que quieres evaluar. Ese vínculo lo estableces tú, así que fija siempre el emisor y el slug esperados y el kid de la clave (véase Confianza e identidad). El repositorio Hodeitek/hodeishield-attest-verifier (licencia Apache-2.0) publica el verificador sin conexión, verify-attestation.sh. La versión actual es la 1.6.2 (15 de octubre de 2026); la última está siempre en la página de versiones del repositorio.

Si no usas un terminal, la misma comprobación se ejecuta en el navegador en verify.hodeishield.com: añades la atestación y el fichero de claves del emisor y lees el resultado. Los ficheros no salen de tu navegador, y el script sigue siendo el verificador de referencia.

Lo que una organización te comparte es un enlace, no un fichero: https://app.hodeishield.com/api/public/attest/<slug>, o sólo el <slug>, la última parte de ese enlace. Descarga el documento justo antes de verificarlo. Un documento es válido como máximo una hora, así que una copia guardada antes, o una que te reenviaron como fichero, falla la comprobación de frescura (termina en EXPIRED) por genuina que sea. Si sólo te enviaron un fichero, pide el enlace.

Requisitos

  • bash ≥ 4 (es bash, no sh POSIX)
  • OpenSSL ≥ 3.5 — necesario para verificar la firma ML-DSA (FIPS 204). Compruébalo con openssl list -signature-algorithms | grep -i ml-dsa-65: si no imprime nada, actualiza. El openssl que trae macOS (y el libressl de Homebrew) es LibreSSL: declara un número de versión 3.5 o superior pero no tiene ML-DSA, y el verificador lo rechaza por su nombre y sale con 2, diciendo que es un límite de tus herramientas y no una prueba contra la atestación. Instala OpenSSL 3.5 o superior, o usa la ruta de contenedor de abajo.
  • python3 (sólo biblioteca estándar) — los bytes canónicos que hay detrás de la firma se re-derivan del JSON de las claims, y eso necesita un analizador JSON; no es opcional
  • curl — sólo para descargar los dos ficheros; la verificación en sí es sin conexión
  • jq — sólo para el modo de revocación (--status-list)
  • Todo lo demás son coreutils. Sin npm, sin Node, sin código de HodeiShield, y sin acceso a red en el momento de verificar (el modo de lista de revocación es la única excepción, y sólo si tú mismo le pasas una URL https://).

Sin instalar nada: la ruta de contenedor

En macOS, Windows y Ubuntu 24.04 LTS el OpenSSL y el bash son demasiado antiguos o no existen para el verificador, y ésta es la ruta soportada: sólo necesitas Docker o Podman (y curl para descargar los dos ficheros). En Windows se ejecuta desde un terminal WSL; en equipos con SELinux y Podman monta con :ro,Z. El comando docker run exacto, fijado por digest de la imagen, está en el README del repositorio, donde se mantiene sincronizado con las pruebas; cópialo de allí.

Pruébalo en vivo

curl -fsS https://app.hodeishield.com/api/public/attest/talmaren-payments -o attestation.json
curl -fsS https://app.hodeishield.com/api/public/attest/keys -o keys.json

./verify-attestation.sh --attestation attestation.json --jwks keys.json \
  --expect-issuer https://app.hodeishield.com --expect-slug talmaren-payments

--attestation recibe el documento exactamente como lo sirve GET /api/public/attest/<slug> — aquí, el Trust Center de talmaren-payments, una organización de demostración con datos ficticios. --jwks recibe el documento de claves del emisor, servido en /api/public/attest/keys. curl -f hace que la descarga falle ante un error HTTP en lugar de guardar la página de error como si fuera la atestación.

El slug de demostración no es una promesa: un sujeto de demostración puede retirarse, y entonces el endpoint responde 404. Con una atestación real, sustituye el slug por el de la organización cuyo documento te dieron, y pásalo a --expect-slug.

Uso básico

verify-attestation.sh --attestation FICHERO (--jwks FICHERO | --pub-b64url CLAVE)
                      --expect-slug SLUG --expect-issuer ORIGEN
                      [--expect-kid KID]... [--expect-nonce CADENA]
                      [--max-age-seconds N] [--raw] [--now EPOCH]
  • --attestation — el documento completo ({"attestation":{"claims":…,"signature":…}}); también se acepta un objeto {"claims","signature"} a secas. Las entradas alternativas son --jws con --claims, y --posture (un objeto de claims completo; una postura suelta se rechaza).
  • --jwks o --pub-b64url — dos fuentes alternativas de la clave de firma: el documento de claves del emisor, o una única clave pública base64url en bruto. No se pueden combinar (salida 2). --pub-b64url no lleva JWK, así que la regla de clave retirada de abajo no se le aplica.
  • --expect-slug — falla a menos que la postura sea de este slug de trust center. Pásalo siempre: sin él, una atestación válida de otra organización se verifica igual de bien.
  • --expect-issuer — falla a menos que el iss de las claims sea igual a este origen. Pásalo siempre: iss decide de quién es el conjunto de claves autorizado. Sin él el script sólo imprime un aviso y aun así puede dar VERIFIED.
  • --expect-kid KID — exige que la clave de firma tenga este kid; repítelo para fijar dos claves durante un solape de rotación. Si no coincide, sale con 1 y unexpected_kid; un valor que no tiene la forma de un kid (22 caracteres base64url) sale con 2. Véase Confianza e identidad.
  • --expect-nonce VALOR — exige que el desafío que emitiste vuelva en las claims firmadas ('' exige que no haya ninguno).
  • --max-age-seconds N / --max-age-days N — tolerancia de antigüedad sobre generatedAt (por defecto 3600 = 1 hora).
  • --raw — imprime además el JSON de la postura (véase Qué muestra la salida).

Ejecuta verify-attestation.sh --help para la lista completa, incluido el modo de revocación de abajo. Si puedes leer el script, puedes auditar toda la comprobación: es bash y Python, sin llamadas de red ocultas más allá de los ficheros y URLs que tú mismo le pases.

Qué muestra la salida

Las comprobaciones se imprimen como líneas PASS, WARN y FAIL en secciones numeradas, y la última línea es el veredicto. Lo que el documento dice — su banda global, el nombre y la banda de cada marco, el sujeto, generatedAt, lastCheckedAt y la visibilidad — se imprime en un bloque «Attested content» justo antes del veredicto, sólo cuando la ejecución termina en VERIFIED (GOOD en modo de revocación). Un documento alterado, caducado, revocado o desconocido, o que no se pudo comprobar, no muestra nada de eso: la salida dice attested content withheld: this document did not verify. El JSON completo de la postura firmada se imprime sólo con --raw, bajo la misma regla.

Todo valor tomado de un documento o de un conjunto de claves se imprime con los caracteres de control y cualquier byte fuera del ASCII imprimible como un escape visible \xHH, de modo que un documento editado no pueda falsificar líneas como un veredicto VERIFIED. El script imprime en inglés; los mensajes citados en esta página son literales.

Códigos de salida

Código Significado (modo atestación)
0 Verificada. La firma es válida y todas las comprobaciones pedidas pasaron.
1 Una comprobación falló, así que no te fíes del documento.
2 No se pudo comprobar: falta una herramienta, un fichero ilegible, un OpenSSL sin ML-DSA, una clave desconocida o un documento de claves con un hs_retired_at mal formado. No dice nada del documento.

Un documento genuino que sólo está caducado también sale con 1, pero su última línea lo distingue de uno manipulado: empieza por EXPIRED — the signature is valid, but this attestation expired on … (el script imprime este texto en inglés) y muestra el comando para descargar una copia nueva, mientras que cualquier otro fallo termina en VERIFICATION FAILED.

Claves retiradas. Una clave que ya no se usa para firmar se mantiene en el documento de claves para que los documentos anteriores todavía se puedan comprobar, marcada con el miembro hs_retired_at (YYYY-MM-DDTHH:MM:SSZ, UTC, sin fracción ni desfase). Un documento generado en ese instante o después sale con 1 y una línea FAIL retired_key, aunque su firma sea válida: una clave retirada no puede haberlo producido. Termina en VERIFICATION FAILED, no en EXPIRED, porque una copia nueva firmada por la misma clave fallaría igual. La aplicación de la clave retirada y --expect-kid requieren la versión v1.3.0 del verificador o posterior; las anteriores ignoran hs_retired_at.

El modo de revocación (--status-list) tiene su propia tabla:

Código Significado (--status-list)
0 Bueno: las comprobaciones de postura pasaron y el documento no está revocado.
1 Revocado, o falló la comprobación de postura del documento que diste.
2 No se pudo comprobar: flags erróneos, falta una herramienta, una lista que no se pudo descargar o leer.
3 Desconocido: la lista no se verifica, está caducada, retrocedió, nombra a su propio firmante o se emitió en el instante de retirada de su clave o después. Ni bueno ni revocado.

No pruebes nunca $? -ne 0 tratándolo como un único resultado: en el modo de revocación eso mezcla «revocado», «no se pudo comprobar» y «desconocido», que son justo los casos que debes distinguir.

Revocación

Una lista de estado firmada dice si la clave que firmó un documento, o la organización para la que se emitió, ha sido retirada. Es opcional y usa un conjunto de claves distinto:

curl -fsS https://app.hodeishield.com/api/public/attest/status -o status.json
curl -fsS https://app.hodeishield.com/api/public/attest/status-keys -o status-keys.json

./verify-attestation.sh --status-list --status status.json --status-keys status-keys.json \
  --attestation attestation.json --jwks keys.json \
  --expect-issuer https://app.hodeishield.com --expect-slug talmaren-payments

--jwks y --status-keys son conjuntos de claves distintos y nunca son intercambiables. Otras opciones de este modo: --check-kid KID (busca una clave en la lista; no es --expect-kid), --check-subject SLUG, --check-generated-at T y --min-seq N (rechaza una lista anterior a un número de secuencia que ya viste). Lo que la lista puede y no puede decirte está en el §7.1 del documento de verificación.

Confianza e identidad

  • El ejemplo en vivo autentica la clave con la PKI web. Descarga el conjunto de claves por HTTPS desde app.hodeishield.com, así que el vínculo entre esa clave y el emisor se apoya en TLS y DNS de ese origen. No hay otra raíz de confianza para la clave de atestación: ni una autoridad de certificación propia ni un registro de transparencia.
  • Fija el kid de la clave. La huella que hay que fijar es el kid, derivado de los bytes de la clave pública: BASE64URL(SHA-256("hodei-shield.attest.kid.v1" || pub)[0..16]). El verificador lo recalcula, lo imprime y rechaza un documento de claves cuyo kid no coincida con su clave. Para calcularlo tú mismo desde un documento de claves descargado:
python3 -c 'import sys,json,base64,hashlib;[print(base64.urlsafe_b64encode(hashlib.sha256(b"hodei-shield.attest.kid.v1"+base64.urlsafe_b64decode(k["pub"]+"="*(-len(k["pub"])%4))).digest()[:16]).decode().rstrip("=")) for k in json.load(open(sys.argv[1]))["keys"]]' keys.json

Los valores vigentes, y cuál es la clave activa, la retirada o la de la lista de estado, están en docs/security/keys.md (cambian en cada rotación, por eso no se repiten aquí). Después deja que el verificador haga la comparación:

./verify-attestation.sh --attestation attestation.json --jwks keys.json \
  --expect-issuer https://app.hodeishield.com --expect-slug talmaren-payments \
  --expect-kid <el kid que fijaste>

La comparación es con el kid recalculado a partir de los bytes de la clave, nunca con una etiqueta del documento, así que una clave reetiquetada con el kid que fijaste no pasa. No se aplica a la clave que firma la lista de estado. - Con un fichero que te haya enviado otra persona, no tomes el conjunto de claves del mismo paquete. Cualquiera puede fabricar una atestación y unas claves coherentes entre sí. Obtén el conjunto de claves del emisor (o una sola clave, con --pub-b64url) por un canal que no dependa de quien te lo envía, y fija su kid la primera vez. Trata un cambio de clave no anunciado como un incidente.

Qué prueba un VERIFIED, y qué no

Prueba que el documento lo firmó el titular de la clave publicada, que no ha cambiado ni un bit desde entonces, que las marcas de tiempo que contiene no se alteraron tras la firma (el titular de la clave puede firmar la marca de tiempo que quiera) y que la firma es poscuántica (ML-DSA-65, FIPS 204).

No prueba que las afirmaciones sean ciertas: las bandas son la puntuación de HodeiShield sobre la evidencia que aportó la organización. No prueba que la clave pertenezca a Hodeitek (ese vínculo descansa en la PKI web, de ahí la fijación de arriba), ni nada sobre organismos de certificación acreditados, y las atestaciones se firman con claves dedicadas y verificables. Lee el §6 del documento de verificación antes de fiarte de cualquier resultado.

Valor probatorio

Una firma válida prueba la integridad (ni un bit del documento firmado ha cambiado desde que se firmó) y que se firmó con la clave privada que corresponde a la clave pública ML-DSA-65 que publica HodeiShield en /api/public/attest/keys. No prueba de quién es esa clave: ese vínculo descansa en la conexión HTTPS por la que descargaste el conjunto de claves, y por eso fijas su kid (ver Confianza e identidad).

Hora. generatedAt es la hora del reloj del servidor de HodeiShield al firmar. La firma solo muestra que no se cambió después; quien tiene la clave puede firmar cualquier hora, y no interviene ninguna autoridad de sellado de tiempo ni ningún registro. Caducidad. Cada atestación caduca 15 minutos después de generarse (expiresAt, dentro de la firma). El verificador rechaza un documento cuyo expiresAt esté a más de una hora de generatedAt, y uno cuyo generatedAt esté más de 5 minutos en el futuro.

Claves de firma. Las atestaciones se firman con claves dedicadas y verificables.

No es una firma electrónica cualificada ni un sello de tiempo cualificado según eIDAS (Reglamento (UE) n.º 910/2014): no interviene ningún prestador cualificado de servicios de confianza, certificado cualificado ni autoridad de sellado de tiempo. No es una auditoría, ni una certificación, ni una declaración de cumplimiento de ningún marco, y no prueba que la postura sea cierta: los niveles de madurez son la puntuación que HodeiShield hace de la evidencia que aportó la organización. No la presentes como ninguna de ellas.

Fuentes, en el repositorio público del verificador: docs/security/attest-verification.md §4.8 (frescura: generatedAt, expiresAt, el techo de una hora), §6 «Proves» 1–3 y «Does not prove» 1–3 y 5 (integridad, origen, hora, vínculo de la clave, organismos de certificación, los 15 minutos por defecto), §6 punto 8; el script verify-attestation.sh del repositorio del verificador (MAX_TTL_SECONDS=3600, POSTURE_CLOCK_SKEW_SECONDS=300); README.

Comprueba que puede fallar

Un verificador que sólo ha impreso PASS no te ha dicho nada. El README del repositorio muestra tres casos que deben salir con 1 (un campo manipulado, un slug equivocado, un miembro que la firma no cubre); ejecútalos antes de fiarte de un VERIFIED: Convince yourself it can fail.

Verificar una versión publicada

Descarga verify-attestation.sh, SHA256SUMS, SHA256SUMS.sigstore.json y verify-attestation.sh.sigstore.json de la versión que uses y ejecuta:

sha256sum -c SHA256SUMS

cosign verify-blob --bundle verify-attestation.sh.sigstore.json \
  --certificate-identity "https://github.com/Hodeitek/hodeishield-attest-verifier/.github/workflows/release.yml@refs/tags/<TAG>" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  verify-attestation.sh

cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/Hodeitek/hodeishield-attest-verifier/.github/workflows/release.yml@refs/tags/<TAG>" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

Sustituye <TAG> por la etiqueta de la versión. Esto prueba que el fichero se construyó desde esa etiqueta con el flujo de publicación del repositorio; no prueba que el verificador sea correcto. Léelo: por eso es un único script corto.

Compatibilidad

El verificador comprueba los formatos attest.attestation.v1 y attest.statuslist.v1, y ninguna otra versión. Un documento con una versión de formato que no conoce nunca se lee como una anterior: una atestación se detiene con salida 2, una lista de estado es unknown (salida 3). Un cambio en cualquiera de los formatos que los verificadores antiguos no puedan leer se anuncia al menos 90 días antes de que surta efecto. Sólo se da soporte a la última versión: actualiza antes de fiarte de un resultado, y consulta el registro de cambios.

Informar de un problema

Si el verificador no puede ejecutarse o no puede comprobar (salida 2, herramientas antiguas), abre una incidencia con la plantilla de problema de uso. Si una comprobación falla, o un documento difiere de lo que puedes establecer de forma independiente, escribe a security@hodeitek.com con el artefacto, el comando exacto y la salida completa: un fallo de verificación que puedas reproducir se trata como un informe de seguridad (véase SECURITY.md).

Siguiente paso