Skip to content

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? ​

ThreatMitigation
Tara's package store or database is modifiedThe signature is verified with a public key that's preconfigured at the consumer, not fetched from Tara
A package is swapped in transitThe sha256 in phillip.lock and in the signed statement
An unsigned or tampered package gets inThe verifier rejects packages that are unsigned or signed with an unknown key
An approved build is later found to be defectiveThe signed revocation list; a yanked build is refused even when it's in the cache
Rolling back to an older revocation listThe verifier keeps the highest serial it has seen
Chain of trust for digital signatures. When an approver clicks Duyệt (Approve), Tara signs the package manifest. When a version is yanked, Tara re-signs the revocation list. Phillip, Bandum and Ryoma verify the signature with the trust key the administrator distributed, check revocation, and compare the sha256 in phillip.lock before loading. A valid package loads; a bad signature or a yanked version is rejected.TaraApprove and signEd25519 key,at approvalYank and re-signsigns the list,rising serialPackage, manifestname, version, sha256Revocation listsigned, serialBefore loadingPhillip, Bandum andRyoma check thesignature, revocationand that sha256matches phillip.lockLoadvalidRejectinvalidor yankedTrust keypublic key, issued by admin,not fetched from Taraphillip.locklocked version and sha256of each resource

Swipe sideways to see the whole diagram.

Verifiers hold the public key in advance and never fetch it from Tara at check time. So even if the package store or the Tara database is tampered with, an attacker cannot forge a signature.

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.

bash
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.

  1. Add the new key to every verifier and keep the old key.
  2. Whoever operates Tara switches the signing key to the new key and restarts Tara.
  3. Re-sign the released builds with the new key.
  4. 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.

bash
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.

Next steps ​