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
shPOSIX) - 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. Elopensslque trae macOS (y ellibresslde 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--jwscon--claims, y--posture(un objeto de claims completo; una postura suelta se rechaza).--jwkso--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-b64urlno 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 elissde las claims sea igual a este origen. Pásalo siempre:issdecide de quién es el conjunto de claves autorizado. Sin él el script sólo imprime un aviso y aun así puede darVERIFIED.--expect-kid KID— exige que la clave de firma tenga estekid; repítelo para fijar dos claves durante un solape de rotación. Si no coincide, sale con 1 yunexpected_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 sobregeneratedAt(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
kidde la clave. La huella que hay que fijar es elkid, 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 cuyokidno 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).