The Ur Project

Documenting the craft of stacking things so they remain stacked. For a very long time.

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.

RepoRootFingerprint (sha256)
Sandcastle Baseversion 2, since 2026-10-035bc141cbfa3b8a9115ebfc4efa81e2e9e8d7bb34894db7b44592b0b6fe532959
Sandcastle Commonversion 2, since 2026-10-03dc28d9d45e9581837264b33ddf36d8899800c95af796cc3585c287560abeed42
Sandcastle Baseversion 3, since 2026-10-128932a96c368bb5bef9c3ebd8045f88d3bbc29284b0fbea69fb4e1998e2516474
Sandcastle Commonversion 3, since 2026-10-12065a1092f2df4c0a6bd8c585d97ba6369856bf02309011bedbfb1c6e7e31a93f

Up to version 2, one offline root key covered both repos. Since version 3 each repo has its own:

RepoRoot key (keyid)
Sandcastle Basebf94c2341aafa0846752ea0a165bc07f24c5203b8bd02d62507f7fa7cb634935
Sandcastle Common6a5eed5448fc9fe1924276996a915332116072295de0710faaefda585fa79571

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.

RepoManifest signing keySigns
Base9c8084eb4024ab2dc503a3d5b2098095a76fd2093df045dc20ca3073b16ef704packages built before 2026-10-03
Base36558dbbdc9ca7cf7b98b0a25cf96fa97725460cead87ac91b0672c24e5a7c85packages built since (clerk)
Common543df49455f62f44255d46c11c33a07f2ee5e61bdb5217bd66b9b21c74b79bb4packages built before 2026-10-03
Common6ba4ca26d3aec2e6265ca592764c93c54ac1f34932cac9da257c986d53ab3c91packages 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.

KeykeyidEd25519 public key
Image keya7febba87f2fc095d9b4efe6e849e6226cec019fd4f69292e62c1a2fe414b82d62e22cfcdc882044

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.