Verifying the Sandcastle signatures
Don't take my word for it.
Here's how you check, for yourself, that the packages and repository metadata you're installing came from us, and not from somebody sitting in between.
A signature tells you who published a package, not what it was built from. To check that, rebuild it yourself: Verifying reproducible builds.
What pkg can't do for you
Almost all of this is signature checking, and pkg does that on its own, every refresh, without being asked. But a chain of signatures only proves that each link follows from the one before it. It can't tell you the first link is ours. Something from outside the chain has to say so, and that something is the fingerprint table further down.
So there's exactly one step here that's on you, and it's comparing a fingerprint. If you only ever do one thing off this page, do that one.
If you downloaded an official image or your system came pre-installed, then you don't need to worry about this. But if you're subscribing or removing repositories, creating compositions or making your own repositories, then this might become important for you.
What gets signed, and by what
Both Sandcastle repos, Base and Common, carry a chain of TUF root files - metadata/1.root.json, then 2.root.json, and so on. A root file is the list of which keys are allowed to sign what in that repo.
Two kinds of key show up in there:
- The root key - signs root files and nothing else. It's kept offline and only comes out at a key ceremony. Each repo has its own.
- The clerk key - signs the repo metadata (
targets.json,snapshot.json,timestamp.json) and every package manifest (.pkg-meta) published since that clerk took over. Each repo has its own clerk.
A new root only counts if the previous root's root key signed it, and its own key signed it, and it's exactly one version newer. That's what makes the chain a chain: trust any single root in it and a client can walk forward to the newest one by itself. pkg does that on every refresh. None of this part is ours - it's plain TUF: https://theupdateframework.io/
The published fingerprints
A fingerprint is the SHA-256 of a root file, exactly as the repo serves it. Compare against this page. Don't compare against anything the repo handed you - a repo that's been tampered with will cheerfully tell you its own hash.
| Repo | Root | Fingerprint (sha256) |
|---|---|---|
| Sandcastle Base | version 2, since 2026-10-03 | 5bc141cbfa3b8a9115ebfc4efa81e2e9e8d7bb34894db7b44592b0b6fe532959 |
| Sandcastle Common | version 2, since 2026-10-03 | dc28d9d45e9581837264b33ddf36d8899800c95af796cc3585c287560abeed42 |
| Sandcastle Base | version 3, since 2026-10-12 | 8932a96c368bb5bef9c3ebd8045f88d3bbc29284b0fbea69fb4e1998e2516474 |
| Sandcastle Common | version 3, since 2026-10-12 | 065a1092f2df4c0a6bd8c585d97ba6369856bf02309011bedbfb1c6e7e31a93f |
Up to version 2, one offline root key covered both repos. Since version 3 each repo has its own:
| Repo | Root key (keyid) |
|---|---|
| Sandcastle Base | bf94c2341aafa0846752ea0a165bc07f24c5203b8bd02d62507f7fa7cb634935 |
| Sandcastle Common | 6a5eed5448fc9fe1924276996a915332116072295de0710faaefda585fa79571 |
You can read that straight out of a root file yourself:
$ curl -s https://download.ur.foo-projects.org/repo/Sandcastle/Common/metadata/3.root.json \
| jq -r '.signed.roles.root.keyids[]'
6a5eed5448fc9fe1924276996a915332116072295de0710faaefda585fa79571
The clerks rotate every six months, and each rotation adds a root version and its fingerprint here. Older rows stay - they're still the truth about what they signed at the time.
Adding a repo
On a system that doesn't have the repo yet:
$ sudo pkg repo add https://download.ur.foo-projects.org/repo/Sandcastle/Base \
--fingerprint 8932a96c368bb5bef9c3ebd8045f88d3bbc29284b0fbea69fb4e1998e2516474
pkg walks the chain from 1.root.json up to the newest root, checks that every version was signed by the one before it, and pins the newest.
You can hand it the fingerprint of any root in the chain, not just the newest. The plan tells you which version it matched, and everything after that version is proven by the signatures anyway. Hand it a fingerprint that matches no root at all and it refuses, and writes nothing. That refusal is the whole point, so don't go looking for a way around it.
Leave --fingerprint off and pkg repo add tells you it's trusting the anchor on first use, and asks before it writes. --dry-run shows you the fingerprint it would pin and writes nothing.
This needs pkg 0.0.61 or newer.
Checking a system you already have
For each repo it prints three lines:
$ sudo pkg repo list --trust
Sandcastle-Base 10 yes https://download.ur.foo-projects.org/repo/Sandcastle/Base
anchor root v3 sha256 8932a96c...
seen root v3
current root v3 sha256 8932a96c...
- anchor - the root file this system was installed or added with.
- seen - the newest root version this system has accepted so far.
- current - the repo's newest root, walked from the anchor over the network with every signature checked on the way.
current is the one to compare against the table above.
No pkg handy? Same check by hand:
$ curl -s https://download.ur.foo-projects.org/repo/Sandcastle/Base/metadata/3.root.json | sha256sum
$ sha256sum /etc/pkg/sandcastle-base.root.json
The first one has to match the table. The second is whatever anchor is installed on that system.
Checking one package
On top of TUF we sign every package manifest separately. Each .pkg-meta carries an Ed25519 signature over its own contents, made by the key that built it. This isn't part of TUF, and a normal online install doesn't lean on it at all - there's a reason it's there, and it's at the end of this section.
$ curl -sO https://download.ur.foo-projects.org/repo/Sandcastle/Common/pkgs/passt/bin/2026_10_02.cba3570/1/x86_64/pkg-meta
$ sudo pkg verify-sig pkg-meta
signature valid: pkg-meta (pubkey 6ba4ca26d3aec2e6265ca592764c93c54ac1f34932cac9da257c986d53ab3c91)
verify-sig proves one thing: the manifest was signed by the key it says it was signed by. Whether that key is one of ours is the other half of the job, and that's what this list is for. A good signature from a key that isn't on it is not a pass.
| Repo | Manifest signing key | Signs |
|---|---|---|
| Base | 9c8084eb4024ab2dc503a3d5b2098095a76fd2093df045dc20ca3073b16ef704 | packages built before 2026-10-03 |
| Base | 36558dbbdc9ca7cf7b98b0a25cf96fa97725460cead87ac91b0672c24e5a7c85 | packages built since (clerk) |
| Common | 543df49455f62f44255d46c11c33a07f2ee5e61bdb5217bd66b9b21c74b79bb4 | packages built before 2026-10-03 |
| Common | 6ba4ca26d3aec2e6265ca592764c93c54ac1f34932cac9da257c986d53ab3c91 | packages built since (clerk) |
A normal pkg install needs none of this. It gets there through TUF instead: a manifest is only accepted if its hash shows up in current.json, which is the repo's index of what's current, and current.json is itself a TUF target whose hash the clerk-signed targets.json pins under the root you already trust.
So why sign the manifests at all? Because two things actually need them. Image composes check manifest signatures as well, against the keys a composition names. And air-gapped upgrades have nothing else to go on - a bundle carries no live TUF metadata with it.
Checking an image
The images on the download page are signed with a third kind of key, the image key. It sits outside TUF and has nothing to do with the repos: it only attests that an image is what our composer produced.
| Key | keyid | Ed25519 public key |
|---|---|---|
| Image key | a7febba87f2fc095 | d9b4efe6e849e6226cec019fd4f69292e62c1a2fe414b82d62e22cfcdc882044 |
The keyid is the first 8 bytes of the SHA-256 of the public key, and it's the middle field of every image.json.sig.
The signature covers image.json, not the image itself. image.json carries the SHA-256 of every file in the build, so checking an image takes two steps: the signature over image.json, then each file against the hash it records. Plain OpenSSL 3 does the first:
$ B=https://download.ur.foo-projects.org/image/Sandcastle/generic-cloud/x86_64/2026.10.1
$ curl -sO $B/image.json -sO $B/image.json.sig
$ { printf 302a300506032b6570032100
echo d9b4efe6e849e6226cec019fd4f69292e62c1a2fe414b82d62e22cfcdc882044
} | xxd -r -p > image-key.der
$ cut -d' ' -f3 image.json.sig | xxd -r -p > image.json.sig.bin
$ openssl pkeyutl -verify -pubin -keyform DER -inkey image-key.der \
-rawin -in image.json -sigfile image.json.sig.bin
Signature Verified Successfully
The 302a...2100 prefix wraps the raw 32-byte key in the DER header OpenSSL wants; it's the same for every Ed25519 key.
Then the files, from the directory you downloaded them into:
$ jq -r '.files[] | "\(.sha256) \(.path)"' image.json | sha256sum -c --ignore-missing
generic-cloud.qcow2: OK
Air-gapped systems
pkg offline upgrade trusts the keys that signed whatever is already installed. Which means that right after a clerk rotation, the first bundle signed by the new clerk gets refused, every time. That's not a bug - an offline machine has no way of learning about a new key on its own. You tell it.
Keep the list above in a file, one key per line (# comments are fine), and pass it in:
$ sudo pkg offline upgrade bundle.pkgtar --trust-key-file sandcastle.keys
Multi-key files need pkg 0.0.62 or newer. The whole round trip is in Air-gapped system upgrades.
When it doesn't match
Stop. Don't add that repo, and don't upgrade from it. A mismatch means one of three things:
- you're pointed at a different repo than the one you meant;
- something between you and the server changed the files;
- this page is out of date, and you should go check the release notes for a newer root version.
That last one is the only harmless possibility, and it's not the one to assume. Either way I'd like to hear about it - include the output of pkg repo list --trust.