Signed Repository Metadata and the Compromise-Resistant Update Protocol

A package manager that verifies a signature over each downloaded artifact has made a meaningful improvement and has not solved the problem. The signature says the artifact was signed by whoever holds a particular key. It does not say the artifact is the current one, that it is the version the publisher intended for this project, that it has not been replaced by an older signed artifact, or that the repository serving it is the repository that was meant. An attacker who can serve arbitrary responses can replay old signed artifacts indefinitely, and the client will verify each one successfully.

The class of attacks that per-artifact signatures leave open is well catalogued: rollback to a version with a known vulnerability, freeze by withholding updates entirely, mix-and-match by combining metadata from different points in time, and endless data by serving an artifact larger than expected. Defending against all of them requires the metadata describing the repository to be signed, structured, and checked for consistency across time. That is what the role-based metadata model in the Update Framework specifies.

Four roles and why the keys are separate

The framework divides repository metadata into four signed documents, each with its own key and its own update frequency.

The root role lists the keys authorised to sign the other roles, and defines a threshold for each. It changes rarely, and it is the trust anchor: the client’s copy of root is the only thing it trusts a priori.

The targets role lists the artifacts, their version identifiers, their hashes, and their lengths. It changes whenever the repository’s contents change, so it is signed by a key kept in a more protected context than the routine publishing key.

The snapshot role lists the current version numbers of all other metadata files. Its purpose is to prevent mix-and-match: a client that fetches targets metadata from one point in time and timestamp metadata from another can detect the inconsistency because snapshot records which version of each is current together.

The timestamp role asserts that the snapshot metadata currently in effect is the latest. It changes on every repository update, so its key must be online and frequently used — and therefore the most exposed. Keeping it separate means compromising the timestamp key yields only the ability to lie about freshness within a narrow window, not the ability to substitute artifacts.

The key separation is the core idea. A single signing key for everything makes the most frequently used key the weakest link in every guarantee. Splitting by function means each key’s compromise has bounded consequences, and the root role’s threshold can require multiple compromised keys before an attacker can rewrite the trust anchor.

root.json      -> keys for root, targets, snapshot, timestamp (thresholds)
timestamp.json -> version + hash of snapshot.json
snapshot.json  -> version + hash of targets.json (and delegated roles)
targets.json   -> per-artifact path, length, hashes

Verification walks that chain from root to artifact. Each step checks a signature against a key authorised by the document above it, and checks the hash of the document below it. A failure at any step stops the update.

Freshness is a version comparison, not a timestamp

The anti-rollback mechanism is easy to describe and easy to get subtly wrong. Every metadata file carries a version number that increases monotonically. The client stores the highest version it has seen for each role and refuses any document whose version is lower.

Timestamp metadata also carries an explicit expiry. The client refuses timestamp metadata whose expiry has passed, which bounds how long a freeze attack can succeed: an attacker who blocks updates can keep the client on old metadata only until that metadata expires, and expiry is short — days, not months — precisely to keep the window small.

The two checks address different attacks and neither substitutes for the other. Version comparison alone cannot stop a freeze, because an attacker who simply serves nothing leaves the client with no newer document to compare. Expiry alone cannot stop a rollback, because an old document may still be within its expiry window if the attacker can choose which old document to serve. Together they bound the attack: rollback is caught by version comparison, freeze by expiry.

The expiry window is a direct trade. A shorter window narrows the freeze window and increases the failure rate for clients that cannot reach the repository before expiry — air-gapped systems, machines offline for weeks, mirrors that sync slowly. A longer window reduces operational friction and widens the exposure. The specification’s design deliberately errs short, on the argument that a client that cannot refresh metadata is already unable to install anything new.

What thresholds buy

Each role can require $k$ valid signatures out of $n$ authorised keys. For root metadata, a threshold of two or more means a single compromised key cannot rewrite the trust anchor, and the root role’s own rotation rules require the old root to sign the new root as well as the new one — so an attacker who compromises the current root keys still cannot hand clients a new root without the old keys, unless the client is already past the point of trusting the attacker.

The threshold is not free. Every additional required signature is a key that must be available when metadata is published, which means either multiple signing machines or a threshold signature scheme. Availability of the signing infrastructure becomes a publication dependency, and a lost key can block all updates until the root is rotated.

For delegated targets, thresholds interact with delegation in a way worth noting. A repository can delegate a subtree of artifact names to a separate role with its own keys, so a project hosting many packages can let each maintainer sign only their own package’s metadata. The delegation graph is expressed in targets metadata, and the client walks it to find the role responsible for the artifact path it wants. This is what allows a large repository to avoid a single key that every maintainer must hold.

The round-trip cost

Verification requires fetching and checking four metadata documents before the artifact. On a cold cache that is five HTTP requests where a naive client would make one, and the metadata documents themselves are small but not negligible for a repository with many packages — targets metadata for a large registry grows with the number of published artifacts, which is why delegation exists: a client interested in one package need not download the whole target list.

Warm-cache behaviour is what makes the scheme practical. Timestamp metadata is the only document fetched on every check, and it is tiny; snapshot and targets metadata are refetched only when their recorded versions change. A client that installs repeatedly from the same repository pays one small request per operation.

The other cost is the update to tooling. Publishing becomes a multi-step operation: sign targets, sign snapshot, sign timestamp, upload in an order that keeps the repository consistent at every instant. A repository that publishes artifacts before metadata leaves a window where clients see the new timestamp but cannot fetch the artifact it names, which is why the correct upload order is artifacts first, then metadata from the inside out.

Where this fits in a dependency graph

Repository metadata signing protects the channel between a repository and a client. It does not say anything about whether a package’s maintainer is trustworthy, whether the package’s source was reviewed, or whether the build that produced the artifact ran the code in the repository’s source tree. Those are provenance questions, addressed by build attestations rather than by signing.

The combination matters because the two mechanisms fail differently. Metadata signing stops a compromised or malicious mirror from serving a different artifact than the repository published. Provenance stops a compromised publisher account from publishing an artifact built from unreviewed source. A dependency chain wants both, and either alone leaves an obvious gap: signed metadata happily distributes a maliciously built artifact, and a perfect attestation is worthless if the mirror serving it substitutes an older one.

For the consumer, the practical consequence is that the integrity digest in a lockfile and repository metadata signing are complementary rather than redundant. The digest pins the bytes the project reviewed; metadata signing ensures the bytes came from the repository. A digest recorded from a compromised mirror pins the wrong bytes permanently, and metadata signing is what prevents that recording.

Failure modes worth designing for

Three failure modes are specific to this scheme and worth naming.

Key loss without compromise. The threshold that protects against compromise also means a lost key can block publication. Root rotation requires the old root’s signatures, so losing enough old root keys permanently prevents a legitimate rotation, and clients must be updated out of band. The mitigation is procedural: root keys stored offline with documented recovery, and rotation performed on a schedule rather than only when forced.

Clock skew. Expiry checks depend on the client’s clock. A client whose clock is wrong by more than the timestamp’s remaining validity will reject valid metadata, and one whose clock is far behind will accept metadata that has actually expired. The failure is asymmetric and confusing, since the error message names expiry rather than the clock. Some clients bound the acceptable skew explicitly.

Metadata size growth. Targets metadata grows with the number of artifacts, and a repository that never prunes accumulates entries for every version ever published. Delegation bounds the per-client cost by splitting the name space, but the total repository metadata still grows, and publishing time grows with it.

The design’s overall posture is that every one of these is preferable to the alternative: a repository whose integrity depends on the honesty of whoever operates the mirror. Yanking a version is only meaningful if clients can trust the metadata that reports the yank, and that trust is what the role structure supplies.