Skip to content

Attestation verifier

A HodeiShield attestation is a signed document a customer, auditor or regulator can verify offline — no HodeiShield account, no network call to us at verification time. The signature proves that the holder of a given key signed the document; it does not prove the key belongs to the organisation you mean to assess. That binding is yours to establish, so always pin the expected issuer and slug and the key's kid (see Trust and identity). The Hodeitek/hodeishield-attest-verifier repository (Apache-2.0 license) publishes the offline verifier, verify-attestation.sh. The current version is 1.6.2 (15 October 2026); the latest one is always on the repository's releases page.

If you do not use a terminal, the same check runs in the browser at verify.hodeishield.com: you add the attestation and the issuer's key file and read the result. The files never leave your browser, and the script remains the reference verifier.

What an organisation shares with you is a link, not a file: https://app.hodeishield.com/api/public/attest/<slug>, or just the <slug>, the last part of that link. Fetch the document right before you verify it. A document is valid for at most one hour, so a copy saved earlier, or one forwarded to you as a file, fails the freshness check (it ends EXPIRED) however genuine it is. If you were sent only a file, ask for the link.

Requirements

  • bash ≥ 4 (it is bash, not POSIX sh)
  • OpenSSL ≥ 3.5 — needed for ML-DSA (FIPS 204) signature verification. Check with openssl list -signature-algorithms | grep -i ml-dsa-65: if it prints nothing, upgrade. The openssl that ships with macOS (and Homebrew's libressl) is LibreSSL: it reports a version number of 3.5 or later but has no ML-DSA, and the verifier refuses it by name and exits 2, saying that this is a limit of your tooling and not evidence against the attestation. Install OpenSSL 3.5 or later, or use the container route below.
  • python3 (standard library only) — the canonical bytes behind the signature are re-derived from the claims JSON, and that needs a JSON parser; it is not optional
  • curl — only to fetch the two files; verification itself is offline
  • jq — only for the revocation mode (--status-list)
  • Everything else is coreutils. No npm, no Node, no HodeiShield code, and no network access at verification time (the revocation status-list mode is the one exception, and only if you point it at an https:// URL yourself).

Without installing anything: the container route

On macOS, Windows and Ubuntu 24.04 LTS the OpenSSL and bash are too old or absent for the verifier, and this is the supported route: you need only Docker or Podman (plus curl to fetch the two files). Windows runs it from a WSL terminal; on SELinux hosts with Podman mount with :ro,Z. The exact docker run command, pinned by image digest, is in the repository README, which is where it is kept in sync with the tests; copy it from there.

Try it live

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 takes the document exactly as GET /api/public/attest/<slug> serves it — here, the trust center of talmaren-payments, a demonstration organisation with fictitious data. --jwks takes the publisher's key document, served at /api/public/attest/keys. curl -f makes the download fail on an HTTP error instead of saving the error page as the attestation.

The demo slug is not a promise: a demonstration subject can be retired, and then the endpoint answers 404. With a real attestation, substitute the slug of the organisation whose document you were given, and pass that slug to --expect-slug.

Basic usage

verify-attestation.sh --attestation FILE (--jwks FILE | --pub-b64url KEY)
                      --expect-slug SLUG --expect-issuer ORIGIN
                      [--expect-kid KID]... [--expect-nonce STR]
                      [--max-age-seconds N] [--raw] [--now EPOCH]
  • --attestation — the whole document ({"attestation":{"claims":…,"signature":…}}); a bare {"claims","signature"} object is accepted too. The alternative inputs are --jws with --claims, and --posture (a full claims object; a bare posture is refused).
  • --jwks or --pub-b64url — two alternative sources for the signing key: the publisher's key document, or a single raw base64url public key. They cannot be combined (exit 2). --pub-b64url carries no JWK, so the retired-key rule below does not apply to it.
  • --expect-slug — fail unless the posture is for this trust-center slug. Always pass it: without it, a valid attestation of a different organisation verifies just as well.
  • --expect-issuer — fail unless the claims' iss equals this origin. Always pass it: iss decides whose key set is authoritative. Without it the script only prints a warning and can still report VERIFIED.
  • --expect-kid KID — require the signing key to have this kid; repeat it to pin two keys during a rotation overlap. A mismatch exits 1 with unexpected_kid; a value that is not the shape of a kid (22 base64url characters) exits 2. See Trust and identity.
  • --expect-nonce VALUE — require the challenge you issued to be echoed in the signed claims ('' requires none).
  • --max-age-seconds N / --max-age-days N — staleness tolerance on generatedAt (default 3600 = 1 hour).
  • --raw — also print the posture JSON (see What the output shows).

Run verify-attestation.sh --help for the full list, including the revocation mode below. If you can read the script, you can audit the whole check: it is bash and Python, with no hidden network calls beyond the files and URLs you pass it yourself.

What the output shows

The checks print as PASS, WARN and FAIL lines in numbered sections, and the last line is the verdict. What the document says — its overall band, the name and band of each framework, the subject, generatedAt, lastCheckedAt and visibility — is printed in an «Attested content» block just before the verdict, only when the run ends VERIFIED (GOOD in revocation mode). A document that is altered, expired, revoked or unknown, or that could not be checked, shows none of it: the output says attested content withheld: this document did not verify. The full signed posture JSON is printed only with --raw, under the same rule.

Every value taken from a document or key set is printed with control characters and any byte outside printable ASCII as a visible \xHH escape, so an edited document cannot forge lines such as a VERIFIED verdict. The script prints in English; the messages quoted on this page are verbatim.

Exit codes

Code Meaning (attestation mode)
0 Verified. The signature holds and every requested check passed.
1 A check failed, so do not rely on the document.
2 The check could not be done: a missing tool, an unreadable file, an OpenSSL without ML-DSA, an unknown key, or a key document with a malformed hs_retired_at. It says nothing about the document.

A genuine document that is only out of date also exits 1, but its last line tells it apart from a tampered one: it starts with EXPIRED — the signature is valid, but this attestation expired on … and shows the command to fetch a fresh copy, whereas any other failure ends with VERIFICATION FAILED.

Retired keys. A key that is no longer used for signing stays in the key document so that older documents can still be checked, marked with a member hs_retired_at (YYYY-MM-DDTHH:MM:SSZ, UTC, no fraction or offset). A document generated at or after that instant exits 1 with a FAIL line retired_key, even if its signature is valid: a retired key cannot have produced it. It ends VERIFICATION FAILED, not EXPIRED, because a fresh copy signed by the same key would fail the same way. Retired-key enforcement and --expect-kid need verifier v1.3.0 or later; earlier versions ignore hs_retired_at.

Revocation mode (--status-list) has its own table:

Code Meaning (--status-list)
0 Good: the posture checks passed and the document is not revoked.
1 Revoked, or the posture check of the document you gave failed.
2 Could not check: bad flags, a missing tool, a list that could not be fetched or read.
3 Unknown: the list does not verify, is stale, was rolled back, names its own signer, or was issued at or after the retirement of its key. Neither good nor revoked.

Never test $? -ne 0 and treat it as one outcome: in revocation mode that merges "revoked", "could not check" and "unknown", which are exactly the cases you must tell apart.

Revocation

A signed status list says whether the key that signed a document, or the organisation it was issued for, has been withdrawn. It is optional and uses a separate key set:

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 and --status-keys are different key sets and are never interchangeable. Other options in this mode: --check-kid KID (look a key up in the list; it is not --expect-kid), --check-subject SLUG, --check-generated-at T and --min-seq N (reject a list older than a sequence number you have already seen). What the list can and cannot tell you is in §7.1 of the verification document.

Trust and identity

  • The live example authenticates the key with the Web PKI. It downloads the key set over HTTPS from app.hodeishield.com, so the binding between that key and the issuer rests on TLS and DNS for that origin. There is no other root of trust for the attestation key: no certificate authority of our own, no transparency log.
  • Pin the key's kid. The fingerprint to pin is the kid, derived from the public key bytes: BASE64URL(SHA-256("hodei-shield.attest.kid.v1" || pub)[0..16]). The verifier recomputes it, prints it, and rejects a key document whose kid does not match its key. To compute it yourself from a downloaded key document:
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

The current values, and which key is active, retired or the status-list key, are listed in docs/security/keys.md (they change at each rotation, which is why they are not repeated here). Then let the verifier do the comparison:

./verify-attestation.sh --attestation attestation.json --jwks keys.json \
  --expect-issuer https://app.hodeishield.com --expect-slug talmaren-payments \
  --expect-kid <the kid you pinned>

The comparison is with the kid recomputed from the key bytes, never with a label in the document, so a key relabelled to the kid you pinned does not pass. It does not apply to the key that signs the status list. - For a file someone sent you, do not take the key set from the same package. A self-consistent attestation and key set can be fabricated by anyone. Obtain the issuer's key set (or a single key, with --pub-b64url) from a channel you trust independently of the sender, and pin its kid on first use. Treat an unannounced key change as an incident.

What a VERIFIED proves, and what it does not

It proves that the document was signed by the holder of the published key, that not one bit has changed since, that the timestamps inside it were not altered after signing (the key holder can still sign any timestamp), and that the signature is post-quantum (ML-DSA-65, FIPS 204).

It does not prove that the claims are true: the bands are HodeiShield's scoring of evidence the organisation supplied. It does not prove the key belongs to Hodeitek (that one binding rests on the Web PKI, hence the pinning above), nor anything about accredited certification bodies, and the attestations are signed with dedicated, verifiable keys. Read §6 of the verification document before relying on any result.

Evidential value

A valid signature proves integrity (not one bit of the signed document has changed since it was signed) and that it was signed with the private key matching the ML-DSA-65 public key HodeiShield publishes at /api/public/attest/keys. It does not prove whose key that is: that link rests on the HTTPS connection you downloaded the key set over, which is why you pin its kid (see Trust and identity).

Time. generatedAt is the time on HodeiShield's server clock when it signed. The signature shows only that it was not changed afterwards; the key holder can sign any time, and no timestamp authority or log is involved. Expiry. Each attestation expires 15 minutes after it is generated (expiresAt, inside the signature). The verifier rejects a document whose expiresAt is more than one hour after generatedAt, and one whose generatedAt is more than 5 minutes in the future.

Signing keys. Attestations are signed with dedicated, verifiable keys.

It is not a qualified electronic signature or a qualified timestamp under eIDAS (Regulation (EU) No 910/2014): no qualified trust service provider, qualified certificate or timestamp authority is involved. It is not an audit, a certification or a statement of compliance with any framework, and it does not prove that the posture is true: the maturity bands are HodeiShield's scoring of the evidence the organisation supplied. Do not present it as any of these.

Sources, in the public verifier repository: docs/security/attest-verification.md §4.8 (freshness: generatedAt, expiresAt, the one-hour ceiling), §6 items "Proves" 1–3 and "Does not prove" 1–3 and 5 (integrity, origin, time, key binding, certification bodies, the 15-minute default), §6 item 8; the verify-attestation.sh script in the verifier repository (MAX_TTL_SECONDS=3600, POSTURE_CLOCK_SKEW_SECONDS=300); README.

Convince yourself it can fail

A verifier that has only ever printed PASS has told you nothing. The repository README shows three cases that must each exit 1 (a tampered field, the wrong slug, a member the signature does not cover); run them before trusting a VERIFIED: Convince yourself it can fail.

Verifying a release

Download verify-attestation.sh, SHA256SUMS, SHA256SUMS.sigstore.json and verify-attestation.sh.sigstore.json from the release you use, then:

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

Replace <TAG> with the release tag. This proves the file was built from that tag by the repository's release workflow; it does not prove the verifier is correct. Read it: that is why it is a short, single script.

Compatibility

The verifier checks the formats attest.attestation.v1 and attest.statuslist.v1, and no other version. A document with a format version it does not know is never read as an older one: an attestation stops with exit 2, a status list is unknown (exit 3). A change to either format that older verifiers cannot read is announced at least 90 days before it takes effect. Only the latest release is supported: update before relying on a result, and see the changelog.

Reporting a problem

If the verifier cannot run or cannot check (exit 2, old tooling), open an issue with the usage problem template. If a check fails, or a document differs from what you can establish independently, write to security@hodeitek.com with the artefact, the exact command and the full output: a verification failure you can reproduce is treated as a security report (see SECURITY.md).

Next step