Signed releases and how to verify them

An organization signs each release with an Ed25519 key. Learn what a signature covers, how keys are created, retired and revoked, and how to verify a release with the CLI or by hand.

By The SKaaS team. Last updated . Markdown version

A signature answers one question: did a holder of this organization's signing key approve exactly these bytes? It says nothing about whether the content is safe. See the audit and its limits.

Edition and plan: every edition and every plan. The deployment needs encryption keys to protect the private signing keys. The Compose file of the self-hosted edition passes SKAAS_ENCRYPTION_KEYS to the server, and setup-env.sh generates it, so signing works on a stack that was set up with it. The hosted service sets it as a secret.

What does a signature cover?

The signature covers the release hash, which covers every file's path, content hash, size and executable bit. Change one byte, add a file or remove one, and the hash changes, so the signature no longer fits. The signed message is the text skaas.release.v1, one zero byte and the 64 characters of the release hash. The algorithm is Ed25519.

A key has an identifier that anyone can compute from the public key: sk1_ followed by the first 32 hex characters of the SHA-256 of the 32-byte public key. The signature is stored with the release, in its provenance, as the algorithm, the key identifier and the value.

How do keys work?

Each organization has its own keys. An administrator manages them with the repos:admin scope.

How do keys work?
State Meaning
active The key that signs new releases. An organization has at most one.
retired A key that was replaced. It signs nothing new. Releases that it signed still verify.
revoked A key that you no longer trust, with a reason. Every signature that it made is reported as made by a revoked key.

A key never goes back to an earlier state. Creating a key retires the active one in the same call, so a rotation is one step. The private key is sealed under the deployment's encryption keys and unwrapped only to sign. Retiring a key discards its private key.

When an organization has no active key, new releases stay unsigned. Releases do not change after the fact, so signing starts with the next publish. If an organization has a key and the signing fails, the publish fails with UNAVAILABLE and stores nothing, so a release is never half signed.

The public keys of an organization are served at GET /v1/orgs/{org}/public-keys. They hold the key identifier, the algorithm, the public key and the state and dates. A stranger without a credential gets them when the organization has something public to read, because the keys exist to verify its public releases. When it has nothing public, a stranger gets NOT_FOUND, so that the answer does not show that the organization exists, and a member of the organization reads the keys of its private releases with a credential. A shared cache keeps only what a stranger was given.

Where do I manage the keys?

In the dashboard, under Settings, on the Signing keys page of the organization. It lists each key with its state, its algorithm, when it was created and when it ended, and its public key. An administrator creates a key, retires the active one or revokes a key from there. Revoking asks for a reason and a confirmation, because it cannot be undone. The page never shows a private key. Creating a key needs a signed-in session, not an API key.

A deployment that has not set signing up shows the page with the words "Release signing is not set up on this deployment" and what the operator does: set SKAAS_ENCRYPTION_KEYS, which seals the private keys, and run a server that has the signing service. An organization that has no key yet sees an empty page with a button to create one.

On a release in the skill viewer, the Releases tab shows a Signature block: whether the release is signed, by which key, whether that key is active, retired or revoked, and the command that checks it. The public library does not show the signature, and says so. The CLI reads it.

How do I verify a release with the CLI?

skaas add, skaas update and skaas rollback check the signature of each release against the public keys of its organization, before they write a file. The CLI computes the release hash from the files that it downloaded, so it does not take the hash on trust from the service. The signatures setting decides what happens to a release that is unsigned or that it cannot verify: require refuses it, warn (the default) installs it and prints a warning, and off does not check. A signature that does not verify, and a signature made with a key that the organization revoked, are refused under require and under warn. A retired key is not a failure.

skaas add acme/platform/code-review --signatures require
skaas verify

skaas verify checks every installed skill again, against the keys that the organization lists now, so it finds a key that was revoked after the install. The lockfile records the result of the check of each install in a signature field of the entry: verified with the key and the algorithm, unsigned, or unverifiable. The tool wrote that result to a file of its own for each skill in earlier versions (.skaas/signatures/<name>.json). It writes no such file now, and it moves an old one into the lockfile at the next install. The field is a record of an earlier check, and a lockfile is a text file that anyone can edit, so skaas verify looks again. The settings, the environment variable, the exit codes and the details of the cache are in the CLI overview.

How do I verify a release by hand?

Read the release, which carries the release hash and the signature, and read the public keys. Then check the signature over the message with any Ed25519 library. This is the check in Node.

import { createHash, createPublicKey, verify } from "node:crypto";

// releaseSha256, signature ({ key_id, value }) and keys come from the API responses.
const entry = keys.find((key) => key.key_id === signature.key_id);
if (!entry || entry.state === "revoked") throw new Error("Key unknown or revoked");

const raw = Buffer.from(entry.public_key, "base64url");
const keyId = "sk1_" + createHash("sha256").update(raw).digest("hex").slice(0, 32);
if (keyId !== entry.key_id) throw new Error("The key identifier does not match the key");

const spki = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), raw]);
const publicKey = createPublicKey({ key: spki, format: "der", type: "spki" });
const message = Buffer.concat([
  Buffer.from("skaas.release.v1"),
  Buffer.from([0]),
  Buffer.from(releaseSha256),
]);
const ok = verify(null, message, publicKey, Buffer.from(signature.value, "base64url"));
console.log(ok ? "valid" : "invalid");

Compute releaseSha256 yourself from the files that you downloaded, and do not take it on trust from the service. Otherwise you verify only that the service agrees with itself.

What does a revoked key mean?

Revoke a key when its private half may have leaked. From then on, every signature that it made is reported as made by a revoked key, whenever the signature was made, because the service cannot tell a genuine old signature from a forged one. Rotate to a new key, publish again and move your channels to the new releases. See the runbook on a leaked token and the one on withdrawing a release in docs/runbooks/ of the repository.

What does a signature not tell me?

That the content is safe, that it was reviewed or that its author is who they say they are. The verified mark on a publisher is a separate statement about identity. See Verified publishers. An unsigned release is not a bad release, and a signed release is not a good one.

An anonymous public install cannot fetch the release signature. Under warn it installs with a warning; under require it exits 3. Without a sign-in, skaas verify checks files only and cannot check withdrawal state or current signing-key status.