The Update Framework (TUF) Specification

The Update Framework (TUF) is a security framework designed to protect software update systems from various common attacks. It provides a set of libraries, file formats, and utilities that allow applications to securely obtain and verify files distributed by trusted parties.

Key characteristics include:

• Flexibility: It is not a universal update system itself, but a mechanism that can be integrated into package managers, application updaters, or library managers.
• Security Focus: It aims to protect against attacks like arbitrary installation, rollback, freeze, and mix-and-match attacks, even in environments lacking SSL/TLS.
• Key Management: It minimizes the impact of key compromise by supporting roles with multiple keys and threshold/quorum trust. It explicitly mandates that online keys (used for automation) must not be used for roles that clients ultimately trust for file installation.

The Update Framework (TUF) specification focuses on the interoperability between clients and servers to secure software update systems. It defines the protocols and data structures required to mitigate attacks like rollback, freeze, mix-and-match, and repository compromises.

What is covered (In Scope)

• Metadata Data Models and Schemas: The structure, syntax, semantics, and serialization (e.g., canonical JSON) for core roles: Root, Targets, Snapshot, and Timestamp, as well as standardized extensions.
• Client Verification Workflow: The algorithmic logic, state machine, and failure conditions a client must follow to fetch and validate metadata and target files.
• Delegation and Trust Boundaries: Mechanisms for threshold signing, key delegation, repository segmentation, and key revocation.
• Cryptographic Representation: How hashes, signatures, and key material are encoded and bound to metadata roles.
• Threat Mitigation Definitions: The specific threat models the framework is designed to address.

What is NOT covered (Out of Scope)

• Payload Semantics: The actual content of the target files (e.g., the binaries or containers themselves).
• Transport Protocols: The network layer used for delivery (e.g., HTTP, gRPC, IPFS).
• Cryptographic Primitives: The underlying algorithms (e.g., Ed25519, SHA-256); TUF relies on existing standards.
• Server-Side Architecture: The specific implementation, backend design, or operational tools used to generate metadata or manage keys.

A software update system using TUF follows a two-step lifecycle to securely obtain target files (the files being distributed, such as binaries or packages):

1. Polling: The system periodically instructs the framework to check repositories for updates. The framework only reports updates for target files that are trusted, meaning they are referenced by properly signed and timely metadata.
2. Fetching: When the application decides to download a file, the framework downloads it and performs security checks to ensure the file matches the signed metadata. The application is only granted access to the file after these checks pass. Finally, the application instructs the framework to copy the verified file to a specified location.

Target files are opaque to the framework; it does not care about their internal structure or content, only their cryptographic integrity and metadata signatures.

TUF is designed to ensure that the following attack scenarios are unsuccessful:

• Arbitrary installation attacks: Attackers cannot provide arbitrary files in response to download requests.
• Endless data attacks: Attackers cannot respond with extremely large files to interfere with the client system.
• Extraneous dependencies attacks: Attackers cannot force clients to download unintended dependencies.
• Fast-forward attacks: Attackers cannot arbitrarily increase version numbers in metadata to trick the system.
• Indefinite freeze attacks: Attackers cannot serve the same outdated metadata without the client noticing.
• Malicious mirrors preventing updates: A single repository mirror cannot prevent updates from other valid mirrors.
• Mix-and-match attacks: Attackers cannot trick clients into using a combination of metadata that never existed together on the repository simultaneously.
• Rollback attacks: Attackers cannot trick clients into installing older software than what was previously known to be available.
• Vulnerability to key compromises: Compromising a single key (or fewer than the required threshold) does not compromise the clients.
• Wrong software installation: Attackers cannot provide a file that is not the specific one the client requested.

Working Groups must follow consensus-based due process to ensure equity and fair play. Any person with a direct and material interest has the right to participate by expressing a position, having that position considered, and having the right to appeal.

Minimum requirements include:

• Openness: Participation must be open to all directly and materially affected persons without undue financial barriers. Voting membership cannot be conditional on organization membership or unreasonably restricted by technical qualifications.
• Lack of Dominance: The process must not be dominated by a single interest category, individual, or organization.
• Balance: The WG should seek a balance of interests from diverse categories.
• Coordination and Harmonization: Efforts must be made to resolve conflicts with existing industry standards.
• Consideration of Views: Written views and objections from all Participants must be considered promptly.
• Written Procedures: All governance and development process materials must be available to interested persons.

The delegations object in targets.json allows roles to be delegated authority over specific paths. It contains a keys object (mapping KEYID to KEY) and a roles array.

Each role in the roles array defines:

• name: A unique string for the delegated role.
• keyids: A list of keys authorized for this role.
• threshold: The minimum number of signatures required.
• paths (optional): A list of PATHPATTERN strings (Unix shell globbing) describing trusted paths.
• path_hash_prefixes (optional): A list of HEX_DIGESTs used to describe target paths via SHA-256 prefix matching.
• terminating (optional): A boolean. If true, clients stop processing further delegations if a matching target is not found in this delegation or its descendants.

Conflict Resolution: Delegations are prioritized by their order in the roles array. The first delegation in the array takes precedence over subsequent ones.

{
  "keys" : {
    "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
      "keytype": "ed25519",
      "scheme": "ed25519",
      "keyval": {
        "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
      }
    }
  },
  "roles" : [
    {
      "name": "project",
      "keyids" : [ "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6" ],
      "threshold" : 1,
      "paths": [ "project/file3.txt" ]
    }
  ]
}

To prevent denial-of-service attacks during volatile updates, a repository can use 'consistent snapshots'. This allows a repository to write new metadata and targets without interrupting clients currently reading an existing snapshot.

When consistent snapshots are enabled, the repository must follow specific naming conventions for files on non-volatile storage:

• Metadata files: MUST be named using the pattern VERSION_NUMBER.FILENAME.EXT, where VERSION_NUMBER is the integer version from the metadata.
• Target files: MUST be named using the pattern HASH.FILENAME.EXT. If a metadata file lists $N$ cryptographic hashes for a target, the repository MUST provide $N$ identical copies, each distinguished by its digest in the filename.
• Timestamp metadata: timestamp.EXT MUST be written without a version prefix. It is OPTIONAL to also write a versioned copy (e.g., VERSION_NUMBER.timestamp.EXT) for record-keeping.

Important Constraints:

• Metadata Content: Metadata files MUST NOT include the version prefix in their internal references. If metadata A refers to metadata B as FILENAME.EXT, it must remain FILENAME.EXT inside the file. This prevents forcing offline keys to re-sign metadata every time a version increments.
• Root Metadata Flag: To signal that the repository uses this mechanism, the root metadata MUST include the CONSISTENT_SNAPSHOT attribute set to true at the root level of its keys of attributes.

The license provides a royalty-free, non-exclusive patent license for 'Necessary Claims' required to implement the Specification.

Patent Exclusions

Contributors can exclude specific patent claims from these licensing commitments by issuing an Exclusion Notice. An Exclusion Notice is made by submitting a pull request or commit to the repository's Notices.md file.

Constraints on Exclusions:

• For contributions to Draft Specifications: An Exclusion Notice must be issued within 45 days of the contribution. A contributor cannot issue an exclusion for material that has been in a Draft Deliverable for more than 45 days.
• For Approved Specifications: Contributors may exclude claims prior to the adoption of a Draft Specification as an Approved Specification.

Defensive Termination

If a Licensee files a patent infringement claim against another Licensee regarding an Implementation, the licenses granted under this License to that Licensee are immediately terminated (unless the claim is a direct response to a claim against them or is brought to enforce this License).