Digital signatures and revocation
This page is for people who configure and operate the system. You'll set trusted keys on a machine or service, learn what the system defends against, and know what to do when a version must be yanked. The concepts are in Version locking and digital signatures.
What does the system defend against?
| Threat | Mitigation |
|---|---|
| Tara's package store or database is modified | The signature is verified with a public key that's preconfigured at the consumer, not fetched from Tara |
| A package is swapped in transit | The sha256 in phillip.lock and in the signed statement |
| An unsigned or tampered package gets in | The verifier rejects packages that are unsigned or signed with an unknown key |
| An approved build is later found to be defective | The signed revocation list; a yanked build is refused even when it's in the cache |
| Rolling back to an older revocation list | The verifier keeps the highest serial it has seen |
Swipe sideways to see the whole diagram.
What a signed statement says
For each released version, Tara signs a statement of type tara.package/v2. It records the name (without a namespace), the version, the org that owns the package (an organization slug or a user handle), the channel (official, org, user for a private personal package, or community for a public one), and the sha256 of the package. The verifier requires the org in the statement to match the organization of the package it is loading, so a package can't be passed off as coming from another owner. A user package must belong to the user who installs it. Statements of the older tara.package/v1 form are still verified. They carry center instead of org (centers were replaced by organizations): the former coordinating center maps to aiforge (official), any other center maps to that organization (channel org), and channel community stays community. Update verifiers before Tara signs v2, because an older verifier doesn't accept v2: Phillip first, then Bandum, then Ryoma.
Configure trusted keys
A public key has the form ed25519:<base64>. The administrator distributes the key through a trusted channel, at the same time as the environment configuration. Don't fetch the key from Tara itself and then trust it right away.
On a user machine
Your organization's Phillip install script usually writes the key in advance. If you need to do it yourself, use these three commands to view, add, and remove keys.
ph tara keys
ph tara keys trust ed25519:<key>
ph tara keys remove <keyId>When you add a key, Phillip prints the fingerprint (keyId) and asks for confirmation, so compare the fingerprint with your team lead or administrator before you agree. The PHILLIP_TARA_KEYS variable overrides the configuration, which is handy for CI.
On a server
Bandum and Ryoma receive keys through the service configuration variables BANDUM_TARA_KEYS and RYOMA_TARA_KEYS. Bandum loads only official packages, plus packages of channel org whose org equals its BANDUM_ORG (empty means official only); it rejects user and community packages. In Bandum's configuration, a plugin reference is name@version:sha256 (for aiforge) or acme/name@version:sha256. Guardrails on a user machine must have a trusted key in its service configuration.
Once a key exists, the verifier rejects unsigned packages, packages signed with an unknown key, and packages whose statement doesn't match the name, version, or sha256. If there's no key yet, it checks only the sha256 and shows a warning, and you should treat that as an unsafe state.
Rotate keys
To rotate a key without interruption, follow these steps in order.
- Add the new key to every verifier and keep the old key.
- Whoever operates Tara switches the signing key to the new key and restarts Tara.
- Re-sign the released builds with the new key.
- Remove the old key from the verifiers.
The private signing key is kept outside the database and the package store, including backups. You can put the key in a KMS (Vault or OpenBao, Transit module) so the private key never leaves the KMS. In that case Tara sends the statement out to be signed and receives the signature back. Rotating a key in a KMS follows the same steps.
Yank a version
When a version has a vulnerability or a serious defect, it is yanked with the following command, or on the Portal from the version page. The owner yanks versions of a personal resource, an Owner or Admin of an organization yanks versions of that organization's resources, and PhillipCLI platform staff yank official ones.
ph tara yank <resource-name>@1.0.1 --reason "Short description of the defect"Tara then re-signs the entire revocation list with an increasing serial, in the same transaction as the status change. Verifiers refresh the list and refuse to load that version, and ph tara list warns the projects that lock it. Bandum and Ryoma check the list only at startup, so if a running plugin is yanked, restart the service.
You can view the revocation list at GET /v1/revocations. Each entry has an org, and an entry without one applies to every organization. The shared list holds only official and public packages. Yanks of an organization's private store (channel org) are not public: they are listed at GET /v1/orgs/{org}/revocations, signed on request and readable by members of that organization only. Phillip, Bandum, and Ryoma check both lists for a package of channel org. If Tara hasn't published a list, a verifier with a trusted key refuses, so when you upgrade the system, upgrade Tara before the verifiers. For a build that contains malicious code, Tara also removes the package, so no one can download it afterward.
What to do after yanking
Release a patch or a new version (see Versioning rules), then remind projects to run ph tara outdated and ph tara upgrade. If you suspect data was exposed, tell Security and rotate the related credentials, because yanking only stops further loading and doesn't take back anything that has already run.
Limits
If you install directly with the claude plugin command without going through Phillip, there is no signature check, and the remaining protection is the automated scanner and, in the official store, the review. A kit installed on a user machine runs with the user's permissions, so signatures and the checks are the main barrier. On a server, a kit runs in the node --permission sandbox.