Verifying the Image

You're about to run software that protects where you are. You shouldn't have to trust that the image on the registry is really the one built from the public source. This page shows how to check.

There are two independent things you can verify: that the image was signed by the maintainer, and that it was built from the public source and nothing else.

Where to get it

The image lives on the maintainer's own registry and is mirrored on Docker Hub:

docker pull sambent.dev/sam/hiddenforge:2.0.3
# or the mirror:
docker pull doingfedtime/hiddenforge:2.0.3

Both resolve to the same content, identified by a digest that starts with sha256:2808baad. The digest, not the tag, is what the signatures are over.

1. Check the signatures

The release is signed three separate ways, on purpose, with no dependency on any outside transparency log or third-party service. The verification material lives in the signatures/ folder of the code repository.

Maintainer key (cosign)

Grab the public key from the repo and verify:

cosign verify \
  --key cosign.pub \
  --insecure-ignore-tlog=true \
  sambent.dev/sam/hiddenforge:2.0.3

The --insecure-ignore-tlog=true flag is intentional: these signatures are deliberately kept out of any public transparency log. A successful check confirms the image digest was signed by the maintainer's key.

Post-quantum signature (ML-DSA-65)

A second signature uses ML-DSA-65, a scheme standardized for the era of quantum computers (FIPS 204). Using the files in signatures/:

pqsign verify \
  --pub hiddenforge-mldsa.pub \
  --sig hiddenforge.digest.mldsa \
  --in  hiddenforge.digest

Hardware key (YubiKey / SSH-FIDO2)

The third signature was made by a physical security key, so it can't be produced by software alone:

ssh-keygen -Y verify \
  -f allowed-signers \
  -I sam@sambent.com \
  -n file \
  -s hiddenforge.digest.sig \
  < hiddenforge.digest

All three sign the same image digest. Any one of them confirms authenticity; together they cover different kinds of risk: a leaked software key, a future quantum attack, and impersonation without the hardware token.

2. Reproduce the build yourself

Signatures tell you who signed the image. A reproducible build tells you what's in it: that it was built from the public source and nothing was slipped in along the way.

HiddenForge builds reproducibly. Build the same source commit twice, on any machine, and you get a byte-for-byte identical image with the same digest. That's only possible because the build strips out the few things that normally vary between builds (timestamps and package-manager bookkeeping), so the result depends only on the source.

To check it yourself, check out the release tag and rebuild:

git checkout v2.0.3
docker buildx build \
  --platform linux/amd64 \
  --build-arg SOURCE_DATE_EPOCH=$(git log -1 --format=%ct) \
  --output type=oci,dest=build.tar,rewrite-timestamp=true .

The amd64 image built this way is byte-for-byte identical to the published one: its layers and config match the published linux/amd64 manifest exactly. That confirms the release was built from this public source and nothing else, with no trust in the maintainer required.

Reproducibility applies from 2.0.3 onward. The earlier 2.0.2 image was built before this landed, so rebuild-and-match works for 2.0.3 and later; the signatures cover every published release.

If a check fails

If a signature doesn't verify, or a rebuild doesn't match a release's documented digest, do not run the image. Stop and ask on the project's channels. A failed check is exactly the signal this is here to give you.