From 3de6f1675ff9d4c704b5b51b686fb7ec41d16d41 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Fri, 5 Mar 2021 11:16:57 +0000 Subject: [PATCH 01/21] Publish latest specification v1.0.17 --- index.html | 137 ++ latest/index.html | 4147 ++++++++++++++++++++++++++++++++++++++++++++ v1.0.17/index.html | 4147 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 8431 insertions(+) create mode 100644 index.html create mode 100644 latest/index.html create mode 100644 v1.0.17/index.html diff --git a/index.html b/index.html new file mode 100644 index 0000000..355a852 --- /dev/null +++ b/index.html @@ -0,0 +1,137 @@ + + + + + The Update Framework Specification + + + + +

The Update Framework Specification

+ + diff --git a/latest/index.html b/latest/index.html new file mode 100644 index 0000000..1c283ce --- /dev/null +++ b/latest/index.html @@ -0,0 +1,4147 @@ + + + + The Update Framework Specification + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.17
Last modified: 11 December 2020

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

Note: We strive to make the specification easy to implement, so if you come +across any inconsistencies or experience any difficulty, do let us know by +sending an email to our mailing list, +or by reporting an issue in the specification repo.

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software is commonly updated through software update systems. These systems +can be package managers that are responsible for all of the software that is +installed on a system, application updaters that are only responsible for +individual installed applications, or software library managers that install +software that adds functionality such as plugins or programming language +libraries.

Software update systems all have the common behavior of downloading files +that identify whether updates exist and, when updates do exist, downloading +the files that are required for the update. For the implementations +concerned with security, various integrity and authenticity checks are +performed on downloaded files.

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

Work on TUF began in late 2009. The core ideas are based off of previous +work done by Justin Cappos and Justin Samuel that identified security flaws +in all popular Linux package managers. +More information and current versions of this document can be found at https://theupdateframework.io/

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

TUF’s reference implementation is based on prior work on Thandy, the application +updater for Tor. Its design and this spec +also came from ideas jointly developed in discussion with Thandy’s authors. +The Thandy spec can be found at https://gitweb.torproject.org/thandy.git/tree/specs/thandy-spec.txt

Whereas Thandy is an application updater for an individual software project, +TUF aims to provide a way to secure any software update system. We’re very +grateful to the Tor Project and the Thandy developers for the early discussion +that led to the ideas in Thandy and TUF. Thandy is the hard +work of Nick Mathewson, Sebastian Hahn, Roger Dingledine, Martin Peck, and +others.

1.4. Non-goals

We are not creating a universal update system, but rather a simple and +flexible way that applications can have high levels of security with their +software update systems. Creating a universal software update system would +not be a reasonable goal due to the diversity of application-specific +functionality in software update systems and the limited usefulness that +such a system would have for securing legacy software update systems.

We won’t be defining package formats or even performing the actual update +of application files. We will provide the simplest mechanism possible that +remains easy to use and provides a secure way for applications to obtain and +verify files being distributed by trusted parties.

We are not providing a means to bootstrap security so that arbitrary +installation of new software is secure. In practice this means that people +still need to use other means to verify the integrity and authenticity of +files they download manually.

The framework will not have the responsibility of deciding on the correct +course of action in all error situations, such as those that can occur when +certain attacks are being performed. Instead, the framework will provide +the software update system the relevant information about any errors that +require security decisions which are situation-specific. How those errors +are handled is up to the software update system.

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework should enable applications to be secure from all known attacks +on the software update process. It is not concerned with exposing +information about what software is being updated (and thus what software +the client may be running) or the contents of updates.

The framework should provide means to minimize the impact of key compromise. +To do so, it must support roles with multiple keys and threshold/quorum +trust (with the exception of minimally trusted roles designed to use a +single key). The compromise of roles using highly vulnerable keys should +have minimal impact. Therefore, online keys (keys which are used in an +automated fashion) must not be used for any role that clients ultimately +trust for files they may install.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

Note: When saying the framework protects against an attack, it means the +attack will be unsuccessful. It does not mean that a client will always +successfully update during an attack. Fundamentally, an attacker +positioned to intercept and modify a client’s communication can always +perform a denial of service. Nevertheless, the framework must detect +when a client is unable to update.

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The framework ultimately provides a secure method of obtaining trusted +files. To avoid ambiguity, we will refer to the files the framework is used +to distribute as "target files". Target files are opaque to the framework. +Whether target files are packages containing multiple files, single text +files, or executable binaries is irrelevant to the framework.

The metadata describing target files is the information necessary to +securely identify the file and indicate which roles are trusted to provide +the file. As providing additional information about +target files may be important to some software update systems using the +framework, additional arbitrary information can be provided with any target +file. This information will be included in signed metadata that describes +the target files.

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

In the discussion of roles that follows, it is important to remember that +the framework has been designed to allow a large amount of flexibility for +many different use cases. For example, it is possible to use the framework +with a single key that is the only key used in the entire system. This is +considered to be insecure but the flexibility is provided in order to meet +the needs of diverse use cases.

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section 6.1 +(Key management and migration). If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

In addition, the targets role can delegate full or partial trust to other +roles. Delegating trust means that the targets role indicates another role +(that is, another set of keys and the threshold required for trust) is +trusted to sign target file metadata. Partial trust delegation is when the +delegated role is only trusted for some of the target files that the +delegating role is trusted for.

Delegated roles can further delegate trust to other delegated +roles. This provides for multiple levels of trust delegation where each +role can delegate full or partial trust for the target files they are +trusted for. The delegating role in these cases is still trusted. That is, +a role does not become untrusted when it has delegated trust.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

The snapshot role signs a metadata file that provides information about +the latest version of all targets metadata on the repository +(the top-level targets role and all delegated roles). This information allows +clients to know which metadata files have been updated and also prevents +mix-and-match attacks.

2.1.4. Timestamp role

To prevent an adversary from replaying an out-of-date signed metadata file +whose signature has not yet expired, an automated process periodically signs +a timestamped statement containing the hash of the snapshot file. Even +though this timestamp key must be kept online, the risk posed to clients by +the compromise of this key is minimal.

2.1.5. Mirrors role

Every repository has one or more mirrors from which files can be downloaded +by clients. A software update system using the framework may choose to +hard-code the mirror information in their software or they may choose to use +mirror metadata files that can optionally be signed by a mirrors role.

The importance of using signed mirror lists depends on the application and +the users of that application. There is minimal risk to the application’s +security from being tricked into contacting the wrong mirrors. This is +because the framework has very little trust in repositories.

2.2. Threat model and analysis

We assume an adversary who can respond to client requests, whether by acting +as a man-in-the-middle or through compromising repository mirrors. At +worst, such an adversary can deny updates to users if no good mirrors are +accessible. An inability to obtain updates is noticed by the framework.

If an adversary compromises enough keys to sign metadata, the best that can +be done is to limit the number of users who are affected. The level to +which this threat is mitigated is dependent on how the application is using +the framework. This includes whether different keys have been used for +different signing roles.

A detailed threat analysis is outside the scope of this document. This is +partly because the specific threat posted to clients in many situations is +largely determined by how the framework is being used.

2.3. Protocol, Operations, Usage, and Format (POUF) documents

This specification purposefully leaves many implementation details, +including the metadata file formats, to the discretion of individual +implementations. These details do not affect the security of an +implementation, and so leaving them out of the specification allows this +document to support a greater variety of users. TUF implementers are +encouraged to document the wireline format and design decisions used in +their implementation as a POUF document. POUFs, as described in TAP 11, +allow different adopters to create interoperable implementations of TUF. +POUFs should follow the layout described in TAP 11 and may be made +publicly available in the TAP directory.

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository has one or more mirrors which are the actual +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

The mirrors can be full or partial mirrors as long as the application-side +of the framework can ultimately obtain all of the files it needs. A mirror +is a partial mirror if it is missing files that a full mirror should have. +If a mirror is intended to only act as a partial mirror, the metadata and +target paths available from that mirror can be specified.

Roles, trusted keys, and target files are completely separate between +repositories. A multi-repository setup is a multi-root system. When an +application uses the framework with multiple repositories, the framework +does not perform any "mixing" of the trusted content from each repository. +It is up to the application to determine the significance of the same or +different target files provided from separate repositories.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

The filenames and the directory structure of target files available from +a repository are not specified by the framework. The names of these files +and directories are completely at the discretion of the application using +the framework.

3.1.2. Metadata files

The filenames and directory structure of repository metadata are strictly +defined. All metadata filenames will have an extension (EXT) based on the +metaformat, for example JSON metadata files would have an EXT of json. +The following are the metadata files of top-level roles relative +to the base URL of metadata available from a given repository mirror.

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

When the targets role delegates trust to other roles, each delegated role +provides one signed metadata file. As is the case with the directory +structure of top-level metadata, the delegated files are relative to the +base URL of metadata available from a given repository mirror.

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

All of the formats described below include the ability to add more +attribute-value fields for backwards-compatible format changes. If +a backwards incompatible format change is needed, a new filename can +be used.

4.1. Metaformat

Implementers of TUF may use any data format for metadata files as long as +all fields in this specification are included and TUF clients are able to +interpret them without ambiguity. Implementers should choose a data format +that allows for canonicalization, or one that will decode data +deterministically by default so that signatures can be accurately verified. +The chosen data format should be documented in the POUF of the implementation. +The examples in this document use a subset of the JSON object format, with +floating-point numbers omitted. When calculating the digest of an +object, we use the "canonical JSON" subdialect as described at Canonical JSON.

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

Metadata date-time follows the ISO 8601 standard. The expected +format of the combined date and time string is "YYYY-MM-DDTHH:MM:SSZ". Time is +always in UTC, and the "Z" time zone designator is attached to indicate a +zero UTC offset. An example date-time string is "1985-10-21T01:21:00Z".

4.3. File formats: root.json

The root.json file is signed by the root role’s keys. It indicates +which keys are authorized for all top-level roles, including the root +role itself. Revocation and replacement of top-level role keys, including +for the root role, is done by changing the keys listed for the roles in +this file.

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section 7 goes into more detail on the consequences +of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The snapshot.json file is signed by the snapshot role. It MUST list the +version numbers of the top-level targets metadata and all delegated targets +metadata. It MAY also list their lengths and file hashes.

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

A string giving the path to a file that is relative to a mirror’s base URL +of targets. To avoid surprising behavior when resolving paths, it is +RECOMMENDED that a TARGETPATH uses the forward slash (/) as directory +separator and does not start with a directory separator. The recommendation +for TARGETPATH aligns with the "path-relative-URL string" +definition in the +WHATWG URL specification.

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

A dictionary that specifies one or more hashes of the target file at TARGETPATH, with a string describing the cryptographic hash function +as key and HASH as defined for METAFILES. For example: { "sha256": HASH, ... }.

CUSTOM +

An object. If defined, the elements and values of the CUSTOM object +will be made available to the client application. The format of the CUSTOM object is opaque to the framework, which only needs to know +that the "custom" attribute maps to an object. The CUSTOM object +may include version numbers, dependencies, requirements, or any other data +that the application wants to include to describe the file at TARGETPATH. The application may use this information to guide +download decisions.

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

As explained in the Diplomat paper , +terminating delegations instruct the client not to consider future trust +statements that match the delegation’s pattern, which stops the delegation +processing once this delegation (and its descendants) have been processed. +A terminating delegation for a package causes any further statements about a +package that are not made by the delegated party or its descendants to be +ignored.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, each of which we +discuss next.

"path_hash_prefixes" +: +
A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.
+
"paths" +: +
A list of strings, where each string describes a path that the role is +trusted to provide. Clients MUST check that a target is in one of the +trusted paths of all roles in a delegation chain, not just in a trusted +path of the role that describes the target file. PATHPATTERN can include shell-style wildcards and supports the Unix filename pattern +matching convention. Its format may either indicate a path to a single +file, or to multiple paths with the use of shell-style wildcards. For +example, the path pattern "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt". +Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and +"foo-version-a.tgz", but not "foo-version-alpha.tgz". +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, akin to TARGETPATH.
+

Prioritized delegations allow clients to resolve conflicts between delegated +roles that share responsibility for overlapping target paths. To resolve +conflicts, clients must consider metadata in order of appearance of delegations; +we treat the order of delegations such that the first delegation is trusted +over the second one, the second delegation is trusted more than the third +one, and so on. Likewise, the metadata of the first delegation will override that +of the second delegation, the metadata of the second delegation will override +that of the third one, etc. In order to accommodate prioritized +delegations, the "roles" key in the DELEGATIONS object above points to an array +of delegated roles, rather than to a hash table.

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

The timestamp.json file is signed by the timestamp role. It indicates the latest +version of the snapshot metadata and is frequently re-signed to limit the +amount of time a client can be kept unaware of interference with obtaining +updates.

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

The order of the list of mirrors is important. For any file to be +downloaded, whether it is a metadata file or a target file, the framework on +the client will give priority to the mirrors that are listed first. That is, +the first mirror in the list whose "metacontent" or "targetscontent" include +a path that indicate the desired file can be found there will the first +mirror that will be used to download that file. Successive mirrors with +matching paths will only be tried if downloading from earlier mirrors fails. +This behavior can be modified by the client code that uses the framework to, +for example, randomly select from the listed mirrors.

5. Detailed client workflow

Note: If a step in the following workflow does not succeed (e.g., the update +is aborted because a new metadata file was not signed), the client should +still be able to update again in the future. Errors raised during the update +process should not leave clients in an unrecoverable state.

5.1. Record fixed update start time

Record the time at which the update began as the fixed update start time. +Time is fixed at the beginning of the update workflow to allow +an application using TUF to effectively pause time, in order to ensure that +metadata which has a valid expiration time at the beginning of an update +does not fail an expiration check later in the update workflow.

5.2. Load trusted root metadata

Load the trusted root metadata file. We assume that a good, +trusted copy of this file was shipped with the package manager or software +updater using an out-of-band process. Note that the expiration of the +trusted root metadata file does not matter, because we will attempt to update +it in the next step.

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A _fast-forward attack_ happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file , up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 7 Consistent Snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 7 Consistent Snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a multi-role delegation, + recursively visit each role, and check that each has signed exactly the + same non-custom metadata (i.e., length and hashes) about the target (or + the lack of any such metadata).
    +
  2. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  3. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 7 Consistent Snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. 6. Usage

See https://theupdateframework.io/ for discussion of +recommended usage in various situations.

6.1. Key management and migration

All keys, except those for the timestamp and mirrors roles, should be +stored securely offline (e.g. encrypted and on a separate machine, in +special-purpose hardware, etc.). This document does not prescribe how keys +should be encrypted and stored, and so it is left to implementers of +this document to decide how best to secure them.

To replace a compromised root key or any other top-level role key, the root +role signs a new root.json file that lists the updated trusted keys for the +role. When replacing root keys, an application will sign the new root.json +file with both the new and old root keys. Any time such a change is +required, the root.json file is versioned and accessible by version number, +e.g., 3.root.json.

Clients that have outdated root keys can update to the latest set of trusted +root keys, by incrementally downloading all intermediate root metadata +files, and verifying that each current version of the root metadata is +signed by a threshold of keys specified by its immediate predecessor as well +as a threshold of keys specified by itself. +For example, if there is a 1.root.json that has threshold 2 and a +2.root.json that has threshold 3, 2.root.json MUST be signed by at least 2 +keys defined in 1.root.json and at least 3 keys defined in 2.root.json. The +client starts the root key update process with the latest version of root +metadata available on the client, and stops when no version N+1 (where N is +the latest trusted version) of the root metadata is available from the +repository. This ensures that an outdated client can always correctly +re-trace the chain of trust across multiple root key updates, even if the +latest set of root keys on the client dates back multiple root metadata +versions. See step § 5.3 Update the root role of the client application workflow for more details.

Note that an attacker, who controls the repository, can launch freeze +attacks by withholding new root metadata. The attacker does not need to +compromise root keys to do so. However, these freeze attacks are limited by +the expiration time of the latest root metadata available to the client.

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

7. Consistent Snapshots

So far, we have considered a TUF repository that is relatively static (in +terms of how often metadata and target files are updated). The problem is +that if the repository (which may be a community repository such as PyPI, +RubyGems, CPAN, or SourceForge) is volatile, in the sense that the +repository is continually producing new TUF metadata as well as its targets, +then should clients read metadata while the same metadata is being written +to, they would effectively see denial-of-service attacks. Therefore, the +repository needs to be careful about how it writes metadata and targets. The +high-level idea of the solution is that each snapshot will be contained in a +so-called consistent snapshot. If a client is reading from one consistent +snapshot, then the repository is free to write another consistent snapshot +without interrupting that client.

7.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

Simply put, TUF should write every metadata file as such: if the +file had the original name of filename.ext, then it should be written to +non-volatile storage as version_number.filename.ext, where version_number +is an integer.

On the other hand, consistent target files should be written to +non-volatile storage as digest.filename.ext. This means that if the +referrer metadata lists N cryptographic hashes of the referred file, then +there must be N identical copies of the referred file, where each file will +be distinguished only by the value of the digest in its filename. The +modified filename need not include the name of the cryptographic hash +function used to produce the digest because, on a read, the choice of +function follows from the selection of a digest (which includes the name of +the cryptographic function) from all digests in the referred file.

Additionally, the timestamp metadata (timestamp.json) should also be +written to non-volatile storage whenever it is updated. It is OPTIONAL for +an implementation to write identical copies at +version_number.timestamp.json for record-keeping purposes, because a +cryptographic hash of the timestamp metadata is usually not known in +advance. The same step applies to the root metadata (root.json), although +an implementation must write both root.json and version_number.root.json +because it is possible to download root metadata both with and without +known version numbers. These steps are required because these are the only +metadata files that may be requested without known version numbers.

Most importantly, no metadata file format must be updated to refer to the +names of metadata or target files with their version numbers included. In +other words, if a metadata file A refers to another metadata file B as +filename.ext, then the filename must remain as filename.ext and not +version_number.filename.ext. This rule is in place so that metadata signed +by roles with offline keys will not be forced to sign for the metadata file +whenever it is updated. In the next subsection, we will see how clients +will reproduce the name of the intended file.

Finally, the root metadata should write the Boolean "consistent_snapshot" +attribute at the root level of its keys of attributes. If consistent +snapshots are not written by the repository, then the attribute may either +be left unspecified or be set to the False value. Otherwise, it must be +set to the True value.

Regardless of whether consistent snapshots are ever used or not, all +released versions of root metadata files should always be provided +so that outdated clients can update to the latest available root.

7.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

8. Future directions and open questions

8.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATIONS, in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/v1.0.17/index.html b/v1.0.17/index.html new file mode 100644 index 0000000..1c283ce --- /dev/null +++ b/v1.0.17/index.html @@ -0,0 +1,4147 @@ + + + + The Update Framework Specification + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.17
Last modified: 11 December 2020

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section 7 goes into more detail on the consequences +of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, each of which we +discuss next.

"path_hash_prefixes" +: +
A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.
+
"paths" +: +
A list of strings, where each string describes a path that the role is +trusted to provide. Clients MUST check that a target is in one of the +trusted paths of all roles in a delegation chain, not just in a trusted +path of the role that describes the target file. PATHPATTERN can include shell-style wildcards and supports the Unix filename pattern +matching convention. Its format may either indicate a path to a single +file, or to multiple paths with the use of shell-style wildcards. For +example, the path pattern "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt". +Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and +"foo-version-a.tgz", but not "foo-version-alpha.tgz". +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, akin to TARGETPATH.
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A _fast-forward attack_ happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file , up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 7 Consistent Snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 7 Consistent Snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a multi-role delegation, + recursively visit each role, and check that each has signed exactly the + same non-custom metadata (i.e., length and hashes) about the target (or + the lack of any such metadata).
    +
  2. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  3. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 7 Consistent Snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. 6. Usage

See https://theupdateframework.io/ for discussion of +recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

7. Consistent Snapshots

7.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

7.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

8. Future directions and open questions

8.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATIONS, in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 58ae43abbd43386641f58bc4f8c4c78722066c57 Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Fri, 5 Mar 2021 16:07:15 +0000 Subject: [PATCH 02/21] Publish latest draft specification --- draft/index.html | 4193 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4193 insertions(+) create mode 100644 draft/index.html diff --git a/draft/index.html b/draft/index.html new file mode 100644 index 0000000..ae1b598 --- /dev/null +++ b/draft/index.html @@ -0,0 +1,4193 @@ + + + + The Update Framework Specification + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.17
Last modified: 11 December 2020

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section 7 goes into more detail on the consequences +of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("keys": {
+    KEYID : KEY,
+    ... },
+  "delegations" : [ DELEGATION, ... ])
+}
+

SPEC_VERSION, VERSION, EXPIRES, KEYID, and KEY are the same as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

"keys" +

A list of the public keys to verify signatures of delegated targets roles. +Revocation and replacement of delegated targets roles keys is done by +changing the keys in this field in the delegating role’s metadata.

"delegations" +

A list of DELEGATION objects whose format is the following:

{
+  "name": DELEGATION_NAME,
+  ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+  "paths" : [ PATHPATTERN, ... ]),
+  "terminating": TERMINATING,
+  "min_roles_in_agreement": NUM_ROLES,
+  "roles" : [{
+      "rolename": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD
+    }, ... ]
+}
+

KEYID and THRESHOLD are the same as is described + for the root.json file.

DELEGATION_NAME +: +
A string giving the name of the delegation.
+

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, each of which we +discuss next.

"path_hash_prefixes" +

A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.

"paths" +

A list of strings, where each string describes a path that the role is +trusted to provide. Clients MUST check that a target is in one of the +trusted paths of all roles in a delegation chain, not just in a trusted +path of the role that describes the target file. PATHPATTERN can include shell-style wildcards and supports the Unix filename pattern +matching convention. Its format may either indicate a path to a single +file, or to multiple paths with the use of shell-style wildcards. For +example, the path pattern "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt". +Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and +"foo-version-a.tgz", but not "foo-version-alpha.tgz". +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, akin to TARGETPATH.

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

NUM_ROLES +

An integer describing the minimum number of delegated targets roles that +must be in agreement about targets hashes and lengths entrusted by the +delegation. The delegated targets roles for a given delegation are listed +in its "roles" field.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

Prioritization exists both for delegations and delegated targets roles. That +is, if delegations handle overlapping targets paths, clients MUST consider +them in the order of their appearance in the "delegations" field. The +first delegation is trusted over the second one, the second delegation is +trusted over the third one, and so on. Likewise, in a multi-role delegation, +if NUM_ROLES is less than or equal to half the number of roles in +"roles" field, different groups of roles may have different agreements +on targets hashes or lengths. Such conflicts must be +resolved by prioritizing the first role in the list, that specifies target +metadata agreed to by at least NUM_ROLES.

The metadata files for delegated targets roles have the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "keys": {
+      "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+        }
+      }
+    },
+    "delegations": [
+      {
+        "name": "project-delegation",
+        "paths": [
+          "project/file3.txt"
+        ],
+        "terminating": true,
+        "min_roles_in_agreement": 1,
+        "roles": [
+          {
+            "name": "project",
+            "keyids": [
+              "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+            ],
+            "threshold": 1
+          }
+        ]
+      }
+    ],
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A _fast-forward attack_ happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file , up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 7 Consistent Snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 7 Consistent Snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a multi-role delegation, + recursively visit each role, and check that a defined minimum number of + roles agrees about non-custom metadata, i.e. length and hashes of the + target (or the lack of any such metadata).
    +
  2. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  3. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 7 Consistent Snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. 6. Usage

See https://theupdateframework.io/ for discussion of +recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

7. Consistent Snapshots

7.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

7.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

8. Future directions and open questions

8.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATION, in §4.5 +
DELEGATION_NAME, in §4.5 +
"delegations", in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
"keys", in §4.5 +
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
NUM_ROLES, in §4.5 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From c5e3ad35dd1eaafe523f3842f662ac0c325c0cd4 Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Mon, 24 May 2021 20:03:47 +0000 Subject: [PATCH 03/21] Publish latest specification v1.0.18 --- index.html | 1 + latest/index.html | 199 ++- v1.0.18/index.html | 4224 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4363 insertions(+), 61 deletions(-) create mode 100644 v1.0.18/index.html diff --git a/index.html b/index.html index 355a852..acb0bd0 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

diff --git a/latest/index.html b/latest/index.html index 1c283ce..d4d5909 100644 --- a/latest/index.html +++ b/latest/index.html @@ -368,8 +368,8 @@ /** Subheadings ***************************************************************/ h1 + h2, - #subtitle { - /* #subtitle is a subtitle in an H2 under the H1 */ + #profile-and-date { + /* #profile-and-date is a subtitle in an H2 under the H1 */ margin-top: 0; } h2 + h3, @@ -583,34 +583,28 @@ a[href] { color: #034575; color: var(--a-normal-text); - text-decoration: none; - border-bottom: 1px solid #707070; - border-bottom: 1px solid var(--a-normal-underline); - /* Need a bit of extending for it to look okay */ - padding: 0 1px 0; - margin: 0 -1px 0; + text-decoration: underline #707070; + text-decoration: underline var(--a-normal-underline); + text-decoration-skip-ink: none; } a:visited { color: #034575; color: var(--a-visited-text); - border-bottom-color: #bbb; - border-bottom-color: var(--a-visited-underline); + text-decoration-color: #bbb; + text-decoration-color: var(--a-visited-underline); } - /* Use distinguishing colors when user is interacting with the link */ + /* Indicate interaction with the link */ a[href]:focus, a[href]:hover { - background: #f8f8f8; - background: rgba(75%, 75%, 75%, .25); - background: var(--a-hover-bg); - border-bottom-width: 3px; - margin-bottom: -2px; + text-decoration-thickness: 2px; + text-decoratin } a[href]:active { color: #c00; color: var(--a-active-text); - border-color: #c00; - border-color: var(--a-active-underline); + text-decoration-color: #c00; + text-decoration-color: var(--a-active-underline); } /* Backout above styling for W3C logo */ @@ -1116,9 +1110,12 @@ .toc a { /* More spacing; use padding to make it part of the click target. */ - padding-top: 0.1rem; + padding: 0.1rem 1px 0; /* Larger, more consistently-sized click target */ display: block; + /* Switch to using border-bottom for underlines */ + text-decoration: none; + border-bottom: 1px solid; /* Reverse color scheme */ color: black; color: var(--toclink-text); @@ -1131,6 +1128,13 @@ border-color: #054572; border-color: var(--toclink-visited-underline); } + .toc a:focus, + .toc a:hover { + background: rgba(75%, 75%, 75%, .25); + background: var(--a-hover-bg); + border-bottom-width: 3px; + margin-bottom: -2px; + } .toc a:not(:focus):not(:hover) { /* Allow colors to cascade through from link styling */ border-bottom-color: transparent; @@ -1484,8 +1488,8 @@ } } - - + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.18
Last modified: 29 March 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section § 6.2 Consistent snapshots goes into more +detail on the consequences of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, each of which we +discuss next.

"path_hash_prefixes" +: +
A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.
+
"paths" +: +
A list of strings, where each string describes a path that the role is +trusted to provide. Clients MUST check that a target is in one of the +trusted paths of all roles in a delegation chain, not just in a trusted +path of the role that describes the target file. PATHPATTERN can include shell-style wildcards and supports the Unix filename pattern +matching convention. Its format may either indicate a path to a single +file, or to multiple paths with the use of shell-style wildcards. For +example, the path pattern "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt". +Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and +"foo-version-a.tgz", but not "foo-version-alpha.tgz". +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, akin to TARGETPATH.
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a multi-role delegation, + recursively visit each role, and check that each has signed exactly the + same non-custom metadata (i.e., length and hashes) about the target (or + the lack of any such metadata).
    +
  2. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  3. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATIONS, in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From e812ad3741b163759428ba8a485841488d0cee6a Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Tue, 25 May 2021 16:53:00 +0000 Subject: [PATCH 04/21] Publish latest draft specification --- draft/index.html | 177 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 127 insertions(+), 50 deletions(-) diff --git a/draft/index.html b/draft/index.html index ae1b598..1611154 100644 --- a/draft/index.html +++ b/draft/index.html @@ -368,8 +368,8 @@ /** Subheadings ***************************************************************/ h1 + h2, - #subtitle { - /* #subtitle is a subtitle in an H2 under the H1 */ + #profile-and-date { + /* #profile-and-date is a subtitle in an H2 under the H1 */ margin-top: 0; } h2 + h3, @@ -583,34 +583,28 @@ a[href] { color: #034575; color: var(--a-normal-text); - text-decoration: none; - border-bottom: 1px solid #707070; - border-bottom: 1px solid var(--a-normal-underline); - /* Need a bit of extending for it to look okay */ - padding: 0 1px 0; - margin: 0 -1px 0; + text-decoration: underline #707070; + text-decoration: underline var(--a-normal-underline); + text-decoration-skip-ink: none; } a:visited { color: #034575; color: var(--a-visited-text); - border-bottom-color: #bbb; - border-bottom-color: var(--a-visited-underline); + text-decoration-color: #bbb; + text-decoration-color: var(--a-visited-underline); } - /* Use distinguishing colors when user is interacting with the link */ + /* Indicate interaction with the link */ a[href]:focus, a[href]:hover { - background: #f8f8f8; - background: rgba(75%, 75%, 75%, .25); - background: var(--a-hover-bg); - border-bottom-width: 3px; - margin-bottom: -2px; + text-decoration-thickness: 2px; + text-decoratin } a[href]:active { color: #c00; color: var(--a-active-text); - border-color: #c00; - border-color: var(--a-active-underline); + text-decoration-color: #c00; + text-decoration-color: var(--a-active-underline); } /* Backout above styling for W3C logo */ @@ -1116,9 +1110,12 @@ .toc a { /* More spacing; use padding to make it part of the click target. */ - padding-top: 0.1rem; + padding: 0.1rem 1px 0; /* Larger, more consistently-sized click target */ display: block; + /* Switch to using border-bottom for underlines */ + text-decoration: none; + border-bottom: 1px solid; /* Reverse color scheme */ color: black; color: var(--toclink-text); @@ -1131,6 +1128,13 @@ border-color: #054572; border-color: var(--toclink-visited-underline); } + .toc a:focus, + .toc a:hover { + background: rgba(75%, 75%, 75%, .25); + background: var(--a-hover-bg); + border-bottom-width: 3px; + margin-bottom: -2px; + } .toc a:not(:focus):not(:hover) { /* Allow colors to cascade through from link styling */ border-bottom-color: transparent; @@ -1484,8 +1488,8 @@ } } - - + + - - + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.19
Last modified: 27 May 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section § 6.2 Consistent snapshots goes into more +detail on the consequences of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, each of which we +discuss next.

"path_hash_prefixes" +: +
A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.
+
"paths" +: +
A list of strings, where each string describes a path that the role is +trusted to provide. Clients MUST check that a target is in one of the +trusted paths of all roles in a delegation chain, not just in a trusted +path of the role that describes the target file. PATHPATTERN can include shell-style wildcards and supports the Unix filename pattern +matching convention. Its format may either indicate a path to a single +file, or to multiple paths with the use of shell-style wildcards. For +example, the path pattern "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt". +Likewise, path pattern "foo-version-?.tgz" matches "foo-version-2.tgz" and +"foo-version-a.tgz", but not "foo-version-alpha.tgz". +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, akin to TARGETPATH.
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATIONS, in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 4bc501ac0d7f535008661b8a5c0de674cafc19e6 Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Thu, 27 May 2021 15:21:13 +0000 Subject: [PATCH 06/21] Publish latest draft specification --- draft/index.html | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/draft/index.html b/draft/index.html index 1611154..ed11c12 100644 --- a/draft/index.html +++ b/draft/index.html @@ -598,7 +598,6 @@ a[href]:focus, a[href]:hover { text-decoration-thickness: 2px; - text-decoratin } a[href]:active { color: #c00; @@ -1488,8 +1487,8 @@ } } - - + + - - + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.20
Last modified: 13 July 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section § 6.2 Consistent snapshots goes into more +detail on the consequences of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the key list. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects".

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, +each of which we discuss next.

"path_hash_prefixes" +

"paths" +

A list of strings, where each string is a PATHPATTERN describing a +path that the delegated role is trusted to provide. Clients MUST check that +a target is in one of the trusted paths of all roles in a delegation chain, +not just in a trusted path of the role that describes the target file.

PATHPATTERN supports the Unix shell pattern matching convention +for paths (globbing +pathnames). Its format may either indicate a path to a single file, or to +multiple files with the use of shell-style wildcards (* or ?). +To avoid surprising behavior when matching targets with PATHPATTERN, +it is RECOMMENDED that PATHPATTERN uses the forward slash (/) as +directory separator and does not start with a directory separator, as is +also recommended for TARGETPATH. A path separator in a path SHOULD +NOT be matched by a wildcard in the PATHPATTERN.

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached. Therefore, it MUST temporarily turn on consistent snapshots in +order to download versioned root metadata files as described next.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in §4.3 +
CUSTOM, in §4.5 +
date-time, in §4.2 +
DELEGATIONS, in §4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
+ "ed25519" +
- dfn for keytype, in §4.2 +
- dfn for scheme, in §4.2 +
+
EXPIRES, in §4.3 +
HASH, in §4.4 +
+ HASHES +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
HEX_DIGEST, in §4.5 +
KEY, in §4.2 +
+ KEYID +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
KEYTYPE, in §4.2 +
KEYVAL, in §4.2 +
+ LENGTH +
- dfn for metapath, in §4.4 +
- dfn for targets-obj, in §4.5 +
+
METAFILES, in §4.4 +
+ METAPATH +
- dfn for mirrors, in §4.7 +
- dfn for snapshot, in §4.4 +
+
mirrors.json, in §4.7 +
"path_hash_prefixes", in §4.5 +
PATHPATTERN, in §4.5 +
"paths", in §4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in §4.2 +
- dfn for keyval-ed25519, in §4.2 +
- dfn for keyval-rsa, in §4.2 +
+
+ ROLE +
- dfn for role, in §4.2 +
- dfn for root, in §4.3 +
+
ROLENAME, in §4.5 +
root.json, in §4.3 +
"rsa", in §4.2 +
"rsassa-pss-sha256", in §4.2 +
SCHEME, in §4.2 +
SIGNATURE, in §4.2 +
snapshot.json, in §4.4 +
SPEC_VERSION, in §4.3 +
TARGETPATH, in §4.5 +
TARGETS, in §4.5 +
targets.json, in §4.5 +
TARGETSPATH, in §4.7 +
TERMINATING, in §4.5 +
THRESHOLD, in §4.3 +
timestamp.json, in §4.6 +
URLBASE, in §4.7 +
+ VERSION +
- dfn for metapath, in §4.4 +
- dfn for role, in §4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From a8cd862e9f358498c0ed1260e061d2867b48e278 Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Tue, 7 Sep 2021 13:53:19 +0000 Subject: [PATCH 08/21] Publish latest specification v1.0.22 --- index.html | 1 + latest/index.html | 125 +- v1.0.22/index.html | 4233 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4298 insertions(+), 61 deletions(-) create mode 100644 v1.0.22/index.html diff --git a/index.html b/index.html index 55e2ffe..e8b7ff1 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.22
v1.0.20
v1.0.19
v1.0.18

for the section numbers * - #toc for the Table of Contents (

) - * - ul.index for Indices (term, in §N.M) + * - ul.index for Indices (term, in § N.M) * - table.index for Index Tables (e.g. for properties or elements) * * Structural Markup @@ -1487,8 +1487,8 @@ } } - - + + + + + + + + + + + + + +

The Update Framework Specification

Version: 1.0.22
Last modified: 7 September 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section § 6.2 Consistent snapshots goes into more +detail on the consequences of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

A string giving the name of the delegated role. For example, "projects". +The rolename MUST be unique in the delegations object: multiple roles with +the same rolename are not allowed within a DELEGATIONS.

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, +each of which we discuss next.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 92b85c1fb842c0331e7347a68ece0160b2ff985f Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Tue, 7 Sep 2021 13:55:24 +0000 Subject: [PATCH 09/21] Publish latest specification v1.0.23 --- index.html | 1 + latest/index.html | 12 +- v1.0.23/index.html | 4235 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4243 insertions(+), 5 deletions(-) create mode 100644 v1.0.23/index.html diff --git a/index.html b/index.html index e8b7ff1..7ac54fd 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.23
v1.0.22
v1.0.20
v1.0.19

The Update Framework Specification

Version: 1.0.23
Last modified: 7 September 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

All of the formats described below include the ability to add more +attribute-value fields to objects for backwards-compatible format changes. +Implementers who encounter undefined attribute-value pairs in the format +must include the data when calculating hashes or verifying signatures and must +preserve the data when re-serializing. If a backwards incompatible format change +is needed, a new filename can be used.

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
A boolean indicating whether the repository supports +consistent snapshots. Section § 6.2 Consistent snapshots goes into more +detail on the consequences of enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an object whose format is the following:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

In order to discuss target paths, a role MUST specify only one of the "path_hash_prefixes" or "paths" attributes, +each of which we discuss next.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Tue, 7 Sep 2021 13:57:11 +0000 Subject: [PATCH 10/21] Publish latest specification v1.0.24 --- index.html | 1 + latest/index.html | 17 +- v1.0.24/index.html | 4236 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4246 insertions(+), 8 deletions(-) create mode 100644 v1.0.24/index.html diff --git a/index.html b/index.html index 7ac54fd..eb03e8d 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.24
v1.0.23
v1.0.22
v1.0.20

The Update Framework Specification

Version: 1.0.24
Last modified: 7 September 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. If the hashes do not +match, discard the new snapshot metadata, abort the update cycle, and report +the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. If the new targets metadata file does +not match, discard the new target metadata, abort the update cycle, and +report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Tue, 7 Sep 2021 19:30:52 +0000 Subject: [PATCH 11/21] Publish latest specification v1.0.25 --- index.html | 1 + latest/index.html | 20 +- v1.0.25/index.html | 4240 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4253 insertions(+), 8 deletions(-) create mode 100644 v1.0.25/index.html diff --git a/index.html b/index.html index eb03e8d..c98c0e8 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.25
v1.0.24
v1.0.23
v1.0.22

The Update Framework Specification

Version: 1.0.25
Last modified: 7 September 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Thu, 11 Nov 2021 13:22:42 +0000 Subject: [PATCH 12/21] Publish latest specification v1.0.26 --- index.html | 1 + latest/index.html | 75 +- v1.0.26/index.html | 4247 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4289 insertions(+), 34 deletions(-) create mode 100644 v1.0.26/index.html diff --git a/index.html b/index.html index c98c0e8..c3d4417 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.26
v1.0.25
v1.0.24
v1.0.23

The Update Framework Specification

Version: 1.0.26
Last modified: 21 September 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPS:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
Tap 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

Simply put, every metadata file MUST be named as such: if the +file had the original name of FILENAME.EXT, then it MUST be written to +non-volatile storage as VERSION_NUMBER.FILENAME.EXT, where VERSION_NUMBER +is the integer version number listed in the metadata file.

On the other hand, consistent target files MUST be written to +non-volatile storage as HASH.FILENAME.EXT. This means that if the +referrer metadata lists N cryptographic hashes of the referred file, then +there MUST be N identical copies of the referred file, where each file will +be distinguished only by the value of the digest in its filename. The +modified filename need not include the name of the cryptographic hash +function used to produce the digest because, on a read, the choice of +function follows from the selection of a digest (which includes the name of +the cryptographic function) from all digests in the referred file.

Timestamp metadata (timestamp.EXT) MUST be written to non-volatile storage +without a version prefix whenever it is updated. This is required because +timestamp metadata is the only metadata file that may be requested without known +version numbers. It is OPTIONAL for an implementation to write an identical copy +of timestamp.EXT to the respective VERSION_NUMBER.timestamp.EXT for +record-keeping purposes.

Most importantly, metadata file formats SHALL NOT be updated to refer to the +names of metadata or target files with their consistent snapshot prefix +included. In other words, if a metadata file A refers to another metadata file B +as FILENAME.EXT, then the filename listed in the metadata MUST remain as +FILENAME.EXT and not VERSION_NUMBER.FILENAME.EXT. This rule is in place so that +metadata signed by roles with offline keys will not be forced to sign for the +metadata file whenever it is updated. In the next subsection, we will see how +clients will reproduce the name of the intended file.

Finally, when consistent snapshots are written by the repository the root +metadata MUST write the boolean CONSISTENT_SNAPSHOT attribute at the root +level of its keys of attributes set to the true value. If consistent snapshots +are not written by the repository, then the attribute MAY either be left +unspecified or be set to the false value.

Regardless of whether consistent snapshots are ever used or not, all +released versions of root metadata files MUST always be provided +so that outdated clients can update to the latest available root.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Tue, 11 Jan 2022 10:10:26 +0000 Subject: [PATCH 13/21] Publish latest specification v1.0.27 --- index.html | 1 + latest/index.html | 26 +- v1.0.27/index.html | 4253 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4270 insertions(+), 10 deletions(-) create mode 100644 v1.0.27/index.html diff --git a/index.html b/index.html index c3d4417..d9f2410 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.27
v1.0.26
v1.0.25
v1.0.24

The Update Framework Specification

Version: 1.0.27
Last modified: 14 December 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

However, when CONSISTENT_SNAPSHOTs are in use, there is a RECOMMENDED +mechanism for naming target files on the repository (see § 6.2 Consistent snapshots). If an application using the framework does not +follow these recommendations, but wishes to support self-contained consistent +snapshots the application MUST ensure that target files are persisted in a way +where each target file can be uniquely and consistently addressed.

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Tue, 11 Jan 2022 10:13:43 +0000 Subject: [PATCH 14/21] Publish latest specification v1.0.28 --- index.html | 1 + latest/index.html | 10 +- v1.0.28/index.html | 4253 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4259 insertions(+), 5 deletions(-) create mode 100644 v1.0.28/index.html diff --git a/index.html b/index.html index d9f2410..c666bc7 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.28
v1.0.27
v1.0.26
v1.0.25

The Update Framework Specification

Version: 1.0.28
Last modified: 14 December 2021

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Mon, 18 Apr 2022 18:43:30 +0000 Subject: [PATCH 15/21] Publish latest specification v1.0.29 --- index.html | 1 + latest/index.html | 10 +- v1.0.29/index.html | 4253 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4259 insertions(+), 5 deletions(-) create mode 100644 v1.0.29/index.html diff --git a/index.html b/index.html index c666bc7..780ff21 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.29
v1.0.28
v1.0.27
v1.0.26

The Update Framework Specification

Version: 1.0.29
Last modified: 8 April 2022

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than or equal to the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the +trusted metadata file, discard it, abort the update cycle, and report the +rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than or equal to the version number of the new timestamp +metadata file. If the new timestamp metadata file is older than the +trusted timestamp metadata file, discard it, abort the update cycle, and +report the potential rollback attack.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Thu, 28 Apr 2022 20:50:38 +0000 Subject: [PATCH 16/21] Publish latest specification v1.0.30 --- index.html | 1 + latest/index.html | 29 +- v1.0.30/index.html | 4258 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4276 insertions(+), 12 deletions(-) create mode 100644 v1.0.30/index.html diff --git a/index.html b/index.html index 780ff21..ba83b6e 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.30
v1.0.29
v1.0.28
v1.0.27

The Update Framework Specification

Version: 1.0.30
Last modified: 28 April 2022

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure.
+
+
Check for a rollback attack. The version number of the trusted +root metadata file (version N) MUST be less than the version +number of the new root metadata file (version N+1). Effectively, this means +checking that the version number signed in the new root metadata file is +indeed N+1. If the version of the new root metadata file is less than the version +of the trusted metadata file, discard it, abort the update cycle, and report the +rollback attack. In case they are equal, again discard the new root metadata, but +proceed the update cycle with the already trusted root metadata.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than the version number of the new timestamp +metadata file. If the new timestamp metadata version is less than the trusted +timestamp metadata version, discard it, abort the update cycle, and +report the potential rollback attack. In case they are equal, discard the new +timestamp metadata and abort the update cycle. This is normal and it +shouldn’t raise any error. The reason for aborting the update process is that +there shouldn’t be any changes in the content of this, or any other metadata +files too, considering it has the same version as the already trusted one.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Tue, 24 May 2022 13:32:52 +0000 Subject: [PATCH 17/21] Publish latest draft specification --- draft/index.html | 343 ++++++++++++++++++++++++++--------------------- 1 file changed, 187 insertions(+), 156 deletions(-) diff --git a/draft/index.html b/draft/index.html index ed11c12..3240016 100644 --- a/draft/index.html +++ b/draft/index.html @@ -12,7 +12,7 @@ * - .toc for the Table of Contents (

for the section numbers * - #toc for the Table of Contents (

The Update Framework Specification

Version: 1.0.31
Last modified: 9 September 2022

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (VMware) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

+ +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

All KEYs have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three signature schemes, although TUF +is not restricted to any particular signature scheme, key type, or +cryptographic library:

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters +can define and use any particular keytype, signing scheme, and cryptographic +library.

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa-sha2-nistp256" format is:

{
+  "keytype" : "ecdsa-sha2-nistp256",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered +if a matching target is not found in this delegation.

As explained in the Diplomat paper , +terminating delegations instruct the client not to consider future trust +statements that match this delegation’s pattern, which stops the delegation +processing once this delegation (and its descendants) have been processed. +A terminating delegation for a package causes any further statements about a +package that are not made by the delegated party or its descendants to be +ignored.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure.
+
+
Check for a rollback attack. The version number of the new root +metadata (version N+1) MUST be exactly the version in the trusted root +metadata (version N) incremented by one, that is precisely N+1. +If the version of the new root metadata file is not N+1, discard it, +abort the update cycle, and report the rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than the version number of the new timestamp +metadata file. If the new timestamp metadata version is less than the trusted +timestamp metadata version, discard it, abort the update cycle, and +report the potential rollback attack. In case they are equal, discard the new +timestamp metadata and abort the update cycle. This is normal and it +shouldn’t raise any error. The reason for aborting the update process is that +there shouldn’t be any changes in the content of this, or any other metadata +files too, considering it has the same version as the already trusted one.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object in the relevant + targets metadata (either the top-level targets metadata, or a delegated + targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

+ +

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2 +
DELEGATIONS, in § 4.5 +
+ "ecdsa-sha2-nistp256" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
+ "ed25519" +
- dfn for keytype, in § 4.2 +
- dfn for scheme, in § 4.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2 +
+ KEYID +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2 +
KEYVAL, in § 4.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2 +
- dfn for keyval-ed25519, in § 4.2 +
- dfn for keyval-rsa, in § 4.2 +
+
+ ROLE +
- dfn for role, in § 4.2 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2 +
"rsassa-pss-sha256", in § 4.2 +
SCHEME, in § 4.2 +
SIGNATURE, in § 4.2 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 4483c1ef3a2e570d904e92eb96bf9e1edf5b115d Mon Sep 17 00:00:00 2001 From: TUF Specification Automation Date: Tue, 16 May 2023 09:17:36 +0000 Subject: [PATCH 19/21] Publish latest specification v1.0.32 --- index.html | 1 + latest/index.html | 922 +++++----- v1.0.32/index.html | 4280 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4754 insertions(+), 449 deletions(-) create mode 100644 v1.0.32/index.html diff --git a/index.html b/index.html index 8611d07..c3293d8 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.32
v1.0.31
v1.0.30
v1.0.29

The Update Framework Specification

Version: 1.0.32
Last modified: 2 March 2023

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (Verizon) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

4.2.1. Object format

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

4.2.2. Key objects

All KEY objects have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three KEYTYPEs: "rsa", "ed25519", and "ecdsa"; and three signature SCHEMEs: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256". These are documented below.

TUF is not restricted to any particular signature SCHEMEs, KEYTYPEs, or cryptographic library. Adopters can define and use any +particular KEYTYPE, signing SCHEME, and cryptographic library.

Implementing the KEYTYPEs and SCHEMEs below is RECOMMENDED for +all implementations, as this enables interoperability. Conversely, +implementations SHOULD NOT implement the KEYTYPEs and SCHEMEs +that are defined in a different manner than specified, so as to avoid confusion +across implementations.

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa" format is:

{
+  "keytype" : "ecdsa",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.2.3. Date-time

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target +files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered +if a matching target is not found in this delegation.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a threshold of keys specified in +the trusted root metadata file (version N), and (2) a threshold of keys +specified in the new root metadata file being validated (version N+1). If +version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure.
+
+
Check for a rollback attack. The version number of the new root +metadata (version N+1) MUST be exactly the version in the trusted root +metadata (version N) incremented by one, that is precisely N+1. +If the version of the new root metadata file is not N+1, discard it, +abort the update cycle, and report the rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new timestamp metadata file is not +properly signed, discard it, abort the update cycle, and report the signature +failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than the version number of the new timestamp +metadata file. If the new timestamp metadata version is less than the trusted +timestamp metadata version, discard it, abort the update cycle, and +report the potential rollback attack. In case they are equal, discard the new +timestamp metadata and abort the update cycle. This is normal and it +shouldn’t raise any error. The reason for aborting the update process is that +there shouldn’t be any changes in the content of this, or any other metadata +files too, considering it has the same version as the already trusted one.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new snapshot metadata file is not signed +as required, discard it, abort the update cycle, and report the signature +failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a threshold of keys specified in the +trusted root metadata file. If the new targets metadata file is not signed +as required, discard it, abort the update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object + in the relevant targets metadata (either the top-level targets metadata, or + a delegated targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2.3 +
DELEGATIONS, in § 4.5 +
"ecdsa", in § 4.2.2 +
"ecdsa-sha2-nistp256", in § 4.2.2 +
+ "ed25519" +
- dfn for keytype, in § 4.2.2 +
- dfn for scheme, in § 4.2.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2.2 +
+ KEYID +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2.2 +
KEYVAL, in § 4.2.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2.2 +
- dfn for keyval-ed25519, in § 4.2.2 +
- dfn for keyval-rsa, in § 4.2.2 +
+
+ ROLE +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2.2 +
"rsassa-pss-sha256", in § 4.2.2 +
SCHEME, in § 4.2.2 +
SIGNATURE, in § 4.2.1 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Thu, 17 Aug 2023 21:14:08 +0000 Subject: [PATCH 20/21] Publish latest specification v1.0.33 --- index.html | 1 + latest/index.html | 365 ++-- v1.0.33/index.html | 4301 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 4495 insertions(+), 172 deletions(-) create mode 100644 v1.0.33/index.html diff --git a/index.html b/index.html index c3293d8..01bd1ec 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.33
v1.0.32
v1.0.31
v1.0.30

The Update Framework Specification

Version: 1.0.33
Last modified: 14 April 2023

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Datadog) +; Joshua Lock (Verizon) +; Marina Moore (NYU) +; Lukas Pühringer (NYU) +

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section § 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

4.2.1. Object format

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

Note: The "signatures" list SHOULD only contain one SIGNATURE per KEYID. This helps prevent multiple signatures by the same key +being counted erroneously towards the minimum THRESHOLD indicating valid +metadata. THRESHOLD counting is further described in the relevant steps +of § 5 Detailed client workflow.

4.2.2. Key objects

All KEY objects have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three KEYTYPEs: "rsa", "ed25519", and "ecdsa"; and three signature SCHEMEs: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256". These are documented below.

TUF is not restricted to any particular signature SCHEMEs, KEYTYPEs, or cryptographic library. Adopters can define and use any +particular KEYTYPE, signing SCHEME, and cryptographic library.

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
+

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa" format is:

{
+  "keytype" : "ecdsa",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.2.3. Date-time

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +: +
A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).
+
CONSISTENT_SNAPSHOT +: +
An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section § 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.
+
VERSION +: +
An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.
+
EXPIRES +: +
A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.
+
ROLE +: +
One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.
+
KEYID +: +
A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any KEYID represented in this key list and in other files, +only one unique key has that KEYID.
+
THRESHOLD +: +
An integer number of keys of that role whose signatures are required in +order to consider a file as being properly signed by that role.
+

+ A root.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at METAPATH. For example: { "sha256": HASH, ... }. HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ A snapshot.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no TARGETPATH elements. This can be used to indicate that no target +files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

CUSTOM +

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the root.json file.

ROLENAME +

TERMINATING +

A boolean indicating whether subsequent delegations should be considered +if a matching target is not found in this delegation.

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths "targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches "foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ A targets.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the snapshot.json file.

+ A signed timestamp.json example file: +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a THRESHOLD of keys +specified in the trusted root metadata file (version N), and (2) a THRESHOLD of keys specified in the new root metadata file being +validated (version N+1). When computing the THRESHOLD each KEY MUST only contribute one SIGNATURE. That is, each SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified SIGNATURE from that KEYID towards the THRESHOLD. +If version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step § 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the new root +metadata (version N+1) MUST be exactly the version in the trusted root +metadata (version N) incremented by one, that is precisely N+1. +If the version of the new root metadata file is not N+1, discard it, +abort the update cycle, and report the rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper for more details.
+
+
Set whether consistent snapshots are used as per the trusted root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a THRESHOLD of keys specified +in the trusted root metadata file. When computing the THRESHOLD each KEY MUST only contribute one SIGNATURE. That is, each SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified SIGNATURE from that KEYID towards the THRESHOLD. If the +new timestamp metadata file is not properly signed, discard it, abort the +update cycle, and report the signature failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than the version number of the new timestamp +metadata file. If the new timestamp metadata version is less than the trusted +timestamp metadata version, discard it, abort the update cycle, and +report the potential rollback attack. In case they are equal, discard the new +timestamp metadata and abort the update cycle. This is normal and it +shouldn’t raise any error. The reason for aborting the update process is that +there shouldn’t be any changes in the content of this, or any other metadata +files too, considering it has the same version as the already trusted one.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a THRESHOLD of keys specified in +the trusted root metadata file. When computing the THRESHOLD each KEY MUST only contribute one SIGNATURE. That is, each SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified SIGNATURE from that KEYID towards the THRESHOLD. If the +new snapshot metadata file is not signed as required, discard it, abort the +update cycle, and report the signature failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see § 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a THRESHOLD of keys specified +in the trusted root metadata file. When computing the THRESHOLD each KEY MUST only contribute one SIGNATURE. That is, each SIGNATURE which is counted towards the THRESHOLD MUST have a +unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified SIGNATURE from that KEYID towards the THRESHOLD. If the +new targets metadata file is not signed as required, discard it, abort the +update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object + in the relevant targets metadata (either the top-level targets metadata, or + a delegated targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2.3 +
DELEGATIONS, in § 4.5 +
"ecdsa", in § 4.2.2 +
"ecdsa-sha2-nistp256", in § 4.2.2 +
+ "ed25519" +
- dfn for keytype, in § 4.2.2 +
- dfn for scheme, in § 4.2.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2.2 +
+ KEYID +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2.2 +
KEYVAL, in § 4.2.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2.2 +
- dfn for keyval-ed25519, in § 4.2.2 +
- dfn for keyval-rsa, in § 4.2.2 +
+
+ ROLE +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2.2 +
"rsassa-pss-sha256", in § 4.2.2 +
SCHEME, in § 4.2.2 +
SIGNATURE, in § 4.2.1 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.3 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

Date: Thu, 22 Jan 2026 20:28:23 +0000 Subject: [PATCH 21/21] Publish latest specification v1.0.34 --- index.html | 1 + latest/index.html | 1291 +++++++++--- v1.0.34/index.html | 4966 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 5945 insertions(+), 313 deletions(-) create mode 100644 v1.0.34/index.html diff --git a/index.html b/index.html index 01bd1ec..8eb9a12 100644 --- a/index.html +++ b/index.html @@ -131,6 +131,7 @@

The Update Framework Specification

latest
draft
v1.0.34
v1.0.33
v1.0.32
v1.0.31

The Update Framework Specification

Version: 1.0.34
+ Last modified: 22 January 2026

Feedback: +: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework with subject line “[TUF] … message topic …” +
Issue Tracking: +: GitHub +
Editors: +: Justin Cappos (NYU) +; Trishank Karthik Kuppusamy (Apple) +; Joshua Lock (Verizon) +; Marina Moore (Edera) +; Lukas Pühringer (Eclipse) +

Note: We strive to make the specification easy to implement, so if you come +across any inconsistencies or experience any difficulty, do let us know by +messaging us on the CNCF slack channel #tuf, +or by reporting an issue in the specification repo.

1. Introduction

1.1. Scope

This document describes a framework for securing software update systems.

The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD," +"SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119.

1.2. Motivation

Software update systems are vulnerable to a variety of known attacks. This +is generally true even for implementations that have tried to be secure.

1.3. History and credit

The Global Environment for Network Innovations (GENI) +and the National Science Foundation (NSF) have +provided support for the development of TUF.

TUF’s reference implementation is based on prior work on +Thandy, the application +updater for Tor. Its design and this spec +also came from ideas jointly developed in discussion with Thandy’s authors. +The Thandy spec can be found at +https://gitweb.torproject.org/thandy.git/tree/specs/thandy-spec.txt +

1.4. Non-goals

1.5. Goals

We need to provide a framework (a set of libraries, file formats, and +utilities) that can be used to secure new and existing software update +systems.

The framework must be flexible enough to meet the needs of a wide variety of +software update systems.

The framework must be easy to integrate with software update systems.

1.5.1. Goals for implementation

+
The client side of the framework must be straightforward to implement in any +programming language and for any platform with the requisite networking and +crypto support.
+
+
The process by which developers push updates to the repository must be +simple.
+
+
The framework must be secure to use in environments that lack support for +SSL (TLS). This does not exclude the optional use of SSL when available, +but the framework will be designed without it.
+

1.5.2. Goals to protect against specific attacks

+
Arbitrary installation attacks. An attacker cannot install anything +they want on the client system. That is, an attacker cannot provide +arbitrary files in response to download requests.
+
+
Endless data attacks. An attacker cannot respond to client +requests with huge amounts of data (extremely large files) that interfere +with the client’s system.
+
+
Extraneous dependencies attacks. An attacker cannot cause clients +to download or install software dependencies that are not the intended +dependencies.
+
+
Fast-forward attacks. An attacker cannot arbitrarily increase the +version numbers of metadata files, listed in the snapshot metadata, well +beyond the current value and thus tricking a software update system into +thinking any subsequent updates are trying to rollback the package to a +previous, out-of-date version. In some situations, such as those where +there is a maximum possible version number, the perpetrator cannot use a +number so high that the system would never be able to match it with the +one in the snapshot metadata, and thus new updates could never be +downloaded.
+
+
Indefinite freeze attacks. An attacker cannot respond to client +requests with the same, outdated metadata without the client being aware +of the problem.
+
+
Malicious mirrors preventing updates. A repository mirror cannot +prevent updates from good mirrors.
+
+
Mix-and-match attacks. An attacker cannot trick clients into using +a combination of metadata that never existed together on the repository +at the same time.
+
+
Rollback attacks. An attacker cannot trick clients into installing +software that is older than that which the client previously knew to be +available.
+
+
Vulnerability to key compromises. An attacker, who is able to +compromise a single key or less than a given threshold of keys, cannot +compromise clients. This includes compromising a single online key (such +as only being protected by SSL) or a single offline key (such as most +software update systems use to sign files).
+
+
Wrong software installation. An attacker cannot provide a file +(trusted or untrusted) that is not the one the client wanted.
+

1.5.3. Goals for PKI (Public key infrastructure)

+
Software update systems using the framework’s client code interface should +never have to directly manage keys.
+
+
All keys must be easily and safely revocable. Trusting new keys for a role +must be easy.
+
+
For roles where trust delegation is meaningful, a role should be able to +delegate full or limited trust to another role.
+
+
The root of trust must not rely on external PKI. That is, no authority will +be derived from keys outside of the framework.
+

1.5.4. TUF Augmentation Proposal (TAP) support

This major version (1.x.y) of the specification adheres to the following TAPs:

+
TAP 6: + Include specification version in metadata
+
+
TAP 9: + Mandatory Metadata signing schemes
+
+
TAP 10: + Remove native support for compressed metadata
+
+
TAP 11: + Using POUFs for Interoperability
+

Implementations compliant with this major version (1.x.y) of the specification +must also comply with the TAPs mentioned above.

2. System overview

The following are the high-level steps of using the framework from the +viewpoint of a software update system using the framework. This is an +error-free case.

Polling +: +
Periodically, the software update system using the framework + instructs the framework to check each repository for updates. If + the framework reports to the application code that there are + updates, the application code determines whether it wants to + download the updated target files. Only target files that are + trusted (referenced by properly signed and timely metadata) are + made available by the framework.
+
Fetching +: +
For each file that the application wants, it asks the framework to + download the file. The framework downloads the file and performs + security checks to ensure that the downloaded file is exactly what + is expected according to the signed metadata. The application code + is not given access to the file until the security checks have been + completed. The application asks the framework to copy the + downloaded file to a location specified by the application. At + this point, the application has securely obtained the target file + and can do with it whatever it wishes.
+

2.1. Roles and PKI

There are four fundamental top-level roles in the framework:

+
Root role
+
+
Targets role
+
+
Snapshot role
+
+
Timestamp role
+

There is also one optional top-level role:

+
Mirrors role
+

All roles can use one or more keys and require a threshold of signatures of +the role’s keys in order to trust a given metadata file.

2.1.1. Root role

The root role delegates trust to specific keys trusted for all other +top-level roles used in the system.

The client-side of the framework MUST ship with trusted root keys for each +configured repository.

The root role’s private keys MUST be kept very secure and thus should be +kept offline. If less than a threshold of Root keys are compromised, the +repository should revoke trust on the compromised keys. This can be +accomplished with a normal rotation of root keys, covered in section +§ 6.1 Key management and migration. If a threshold of root keys is compromised, +the Root keys should be updated out-of-band, however, the threshold should +be chosen so that this is extremely unlikely. In the unfortunate event that +a threshold of keys are compromised, it is safest to assume that attackers +have installed malware and taken over affected machines. For this reason, +making it difficult for attackers to compromise all of the offline keys is +important because safely recovering from it is nearly impossible.

2.1.2. Targets role

The targets role’s signature indicates which target files are trusted by +clients. The targets role signs metadata that describes these files, not +the actual target files themselves.

Any delegation can be revoked at any time: the delegating role needs only +to sign new metadata that no longer contains that delegation.

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

This specification purposefully leaves many implementation details, +including the metadata file formats, to the discretion of individual +implementations. These details do not affect the security of an +implementation, and so leaving them out of the specification allows this +document to support a greater variety of users. TUF implementers are +encouraged to document the wireline format and design decisions used in +their implementation as a POUF document. POUFs, as described in +TAP 11, +allow different adopters to create interoperable implementations of TUF. +POUFs should follow the layout described in TAP 11 and may be made +publicly available in the TAP directory.

3. The repository

An application uses the framework to interact with one or more repositories. +A repository is a conceptual source of target files of interest to the +application. Each repository MAY have one or more mirrors as the +providers of files to be downloaded. For example, each mirror may specify a +different host where files can be downloaded from over HTTP.

3.1. Repository layout

The filesystem layout in the repository is used for two purposes:

+
To give mirrors an easy way to mirror only some of the repository.
+
+
To specify which parts of the repository a given role has authority +to sign/provide.
+

3.1.1. Target files

However, when CONSISTENT_SNAPSHOTs are in use, there is a RECOMMENDED +mechanism for naming target files on the repository (see +§ 6.2 Consistent snapshots). If an application using the framework does not +follow these recommendations, but wishes to support self-contained consistent +snapshots the application MUST ensure that target files are persisted in a way +where each target file can be uniquely and consistently addressed.

3.1.2. Metadata files

/root.EXT +: +
Signed by the root keys; specifies trusted keys for the other +top-level roles.
+
/snapshot.EXT +: +
Signed by the snapshot role’s keys. Lists the version numbers of all +target metadata files: the top-level targets.EXT and all delegated +roles.
+
/targets.EXT +: +
Signed by the target role’s keys. Lists hashes and sizes of target +files. Specifies delegation information and trusted keys for delegated +target roles.
+
/timestamp.EXT +: +
Signed by the timestamp role’s keys. Lists hash(es), size, and version +number of the snapshot file. This is the first and potentially only +file that needs to be downloaded when clients poll for the existence +of updates.
+
/mirrors.EXT (optional) +: +
Signed by the mirrors role’s keys. Lists information about available +mirrors and the content available from each mirror.
+

3.1.2.1. Metadata files for targets delegation

A delegated role file is located at:

/DELEGATED_ROLE.EXT +: +
Where DELEGATED_ROLE is the name of the delegated role that has been +specified in targets.EXT. If this role further delegates trust to a role +named ANOTHER_ROLE, that role’s signed metadata file is made available at:
+
/ANOTHER_ROLE.EXT +: +
Delegated target roles are authorized by the keys listed in the directly +delegating target role.
+

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

4.2.1. Object format

All signed metadata objects have the format:

{
+  "signed" : ROLE,
+  "signatures" : [
+    { "keyid" : KEYID,
+      "sig" : SIGNATURE }
+      , ... ]
+}
+

ROLE +: +
A dictionary whose "_type" field describes the role type.
+
KEYID +: +
The identifier of the key signing the ROLE object, +which is a hexdigest of the SHA-256 hash of the canonical form of the key. +The keyid MUST be unique in the "signatures" array: multiple +signatures with the same keyid are not allowed.
+
SIGNATURE +: +
A hex-encoded signature of the canonical form of the metadata for ROLE.
+

Note: The "signatures" list SHOULD only contain one SIGNATURE per +KEYID. This helps prevent multiple signatures by the same key +being counted erroneously towards the minimum THRESHOLD indicating valid +metadata. THRESHOLD counting is further described in the relevant steps +of § 5 Detailed client workflow.

4.2.2. Key objects

All KEY objects have the format:

{
+  "keytype" : KEYTYPE,
+  "scheme" : SCHEME,
+  "keyval" : KEYVAL
+}
+

KEYTYPE +: +
A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa".
+
SCHEME +: +
A string denoting a corresponding signature scheme. For example: "rsassa-pss-sha256", "ed25519", and "ecdsa-sha2-nistp256".
+
KEYVAL +: +
A dictionary containing the public portion of the key.
+

The reference implementation defines three KEYTYPEs: +"rsa", "ed25519", and +"ecdsa"; and three signature SCHEMEs: +"rsassa-pss-sha256", "ed25519", and +"ecdsa-sha2-nistp256". These are documented below.

TUF is not restricted to any particular signature SCHEMEs, +KEYTYPEs, or cryptographic library. Adopters can define and use any +particular KEYTYPE, signing SCHEME, and cryptographic library.

"rsassa-pss-sha256" +: +
RSA Probabilistic signature scheme with appendix. The underlying hash +function is SHA256. https://tools.ietf.org/html/rfc3447#page-29 +
+
"ed25519" +: +
Elliptic curve digital signature algorithm based on Twisted Edwards curves. +https://ed25519.cr.yp.to/
+
"ecdsa-sha2-nistp256" +: +
Elliptic Curve Digital Signature Algorithm with NIST P-256 curve signing +and SHA-256 hashing. +https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm +
+

The "rsa" format is:

{
+  "keytype" : "rsa",
+  "scheme" : "rsassa-pss-sha256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string. All RSA keys MUST be at least 2048 bits.
+

The "ed25519" format is:

{
+  "keytype" : "ed25519",
+  "scheme" : "ed25519",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
64-byte hex encoded string.
+

The "ecdsa" format is:

{
+  "keytype" : "ecdsa",
+  "scheme" : "ecdsa-sha2-nistp256",
+  "keyval" : {
+    "public" : PUBLIC
+  }
+}
+

PUBLIC +: +
PEM format and a string.
+

4.2.3. Date-time

4.3. File formats: root.json

The "signed" portion of root.json is as follows:

{
+  "_type" : "root",
+  "spec_version" : SPEC_VERSION,
+  "consistent_snapshot": CONSISTENT_SNAPSHOT,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "keys" : {
+    KEYID : KEY,
+    ...
+  },
+  "roles" : {
+    ROLE : {
+      "keyids" : [
+        KEYID,
+        ...
+      ] ,
+      "threshold" : THRESHOLD
+    },
+    ...
+  }
+}
+

SPEC_VERSION +

A string that contains the version number of the TUF +specification. Its format follows the Semantic Versioning 2.0.0 +(semver) specification. Metadata is +written according to version "spec_version" of the specification, and +clients MUST verify that "spec_version" matches the expected version number. +Adopters are free to determine what is considered a match (e.g., the version +number exactly, or perhaps only the major version number (major.minor.fix).

CONSISTENT_SNAPSHOT +

An OPTIONAL boolean indicating whether the repository supports +consistent snapshots. This field is OPTIONAL for backwards compatibility with +old metadata. New implementations SHOULD include it. Section +§ 6.2 Consistent snapshots goes into more detail on the consequences of +enabling this setting on a repository.

VERSION +

An integer that is greater than 0. Clients MUST NOT replace a +metadata file with a version number less than the one currently trusted.

EXPIRES +

A date-time string indicating when metadata should be considered +expired and no longer trusted by clients. Clients MUST NOT trust an +expired file.

ROLE +

One of "root", "snapshot", "targets", "timestamp", or "mirrors". +A role for each of "root", "snapshot", "timestamp", and "targets" MUST be +specified in the roles object. The role of "mirror" is OPTIONAL. If not +specified, the mirror list will not need to be signed if mirror lists are +being used.

KEYID +

A KEYID, which MUST be correct for the specified KEY. +Clients MUST calculate each KEYID to verify this is +correct for the associated key. Clients MUST ensure that for any +KEYID represented in this key list and in other files, +only one unique key has that KEYID.

As before the THRESHOLD must be a positive integer number of keys (>=1) of +that role whose signatures are required in order to consider a file as being +properly signed by that role.

+ +A root.json example file: + + +

{
+  "signatures": [
+    {
+      "keyid": "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4",
+      "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809
+              f32c890c6b801e30158ac4efe0d4d87317223077784c7a378834249d048306"
+    }
+  ],
+  "signed": {
+    "_type": "root",
+    "spec_version": "1.0.0",
+    "consistent_snapshot": false,
+    "expires": "2030-01-01T00:00:00Z",
+    "keys": {
+      "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "72378e5bc588793e58f81c8533da64a2e8f1565c1fcc7f253496394ffc52542c"
+        }
+      },
+      "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "68ead6e54a43f8f36f9717b10669d1ef0ebb38cee6b05317669341309f1069cb"
+        }
+      },
+      "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "66dd78c5c2a78abc6fc6b267ff1a8017ba0e8bfc853dd97af351949bba021275"
+        }
+      },
+      "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc": {
+        "keytype": "ed25519",
+        "scheme": "ed25519",
+        "keyval": {
+          "public": "01c61f8dc7d77fcef973f4267927541e355e8ceda757e2c402818dad850f856e"
+        }
+      }
+    },
+    "roles": {
+      "root": {
+        "keyids": [
+          "cb3fbd83df4ba2471a736b065650878280964a98843ec13b457a99b2a21cc3b4"
+        ],
+        "threshold": 1
+      },
+      "snapshot": {
+        "keyids": [
+          "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc"
+        ],
+        "threshold": 1
+      },
+      "targets": {
+        "keyids": [
+          "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164"
+        ],
+        "threshold": 1
+      },
+      "timestamp": {
+        "keyids": [
+          "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3"
+        ],
+        "threshold": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.4. File formats: snapshot.json

The "signed" portion of snapshot.json is as follows:

{
+  "_type" : "snapshot",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

METAFILES is an object whose format is the following:

{
+  METAPATH : {
+    "version" : VERSION,
+    ("length" : LENGTH,)
+    ("hashes" : HASHES)
+  },
+  ...
+}
+

METAPATH +: +
A string giving the file path of the metadata on the repository relative to +the metadata base URL. For snapshot.json, these are top-level targets +metadata and delegated targets metadata.
+
VERSION +: +
An integer version number as shown in the metadata file at +METAPATH.
+
LENGTH +: +
An integer length in bytes of the metadata file at +METAPATH. It is OPTIONAL and can be omitted to reduce +the snapshot metadata file size. In that case the client MUST use a custom +download limit for the listed metadata.
+
HASHES +: +
A dictionary that specifies one or more hashes of the metadata +file at METAPATH, with the cryptographic hash +function as key and the value as HASH, the hexdigest of the +cryptographic function computed on the metadata file at +METAPATH. For example: { "sha256": HASH, ... }. +HASHES is OPTIONAL and can be omitted to reduce the +snapshot metadata file size. In that case the repository MUST guarantee +that VERSION alone unambiguously identifies +the metadata at METAPATH.
+

+ +A snapshot.json example file: + + +

{
+  "signatures": [
+    {
+      "keyid": "66676daa73bdfb4804b56070c8927ae491e2a6c2314f05b854dea94de8ff6bfc",
+      "sig": "f7f03b13e3f4a78a23561419fc0dd741a637e49ee671251be9f8f3fceedfc112e4
+              4ee3aaff2278fad9164ab039118d4dc53f22f94900dae9a147aa4d35dcfc0f"
+    }
+  ],
+  "signed": {
+    "_type": "snapshot",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "targets.json": {
+        "version": 1
+      },
+      "project1.json": {
+        "version": 1,
+        "hashes": {
+          "sha256": "f592d072e1193688a686267e8e10d7257b4ebfcf28133350dae88362d82a0c8a"
+        }
+      },
+      "project2.json": {
+        "version": 1,
+        "length": 604,
+        "hashes": {
+          "sha256": "1f812e378264c3085bb69ec5f6663ed21e5882bbece3c3f8a0e8479f205ffb91"
+        }
+      }
+    },
+    "version": 1
+  }
+}
+

4.5. File formats: targets.json and delegated target roles

The "signed" portion of targets.json is as follows:

{
+  "_type" : "targets",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "targets" : TARGETS,
+  ("delegations" : DELEGATIONS)
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

TARGETS is an object whose format is the following:

{
+  TARGETPATH : {
+      "length" : LENGTH,
+      "hashes" : HASHES,
+      ("custom" : CUSTOM) }
+  , ...
+}
+

TARGETS +

Each key of the TARGETS object is a TARGETPATH.

TARGETPATH +

It is allowed to have a TARGETS object with no +TARGETPATH elements. This can be used to indicate that no target +files are available.

LENGTH +

An integer length in bytes of the target file at TARGETPATH.

HASHES +

A dictionary that specifies one or more hashes of the target file at +TARGETPATH, with a string describing the cryptographic hash function +as key and HASH as defined for METAFILES. For example: +{ "sha256": HASH, ... }.

CUSTOM +

An object. If defined, the elements and values of the CUSTOM object +will be made available to the client application. The format of the +CUSTOM object is opaque to the framework, which only needs to know +that the "custom" attribute maps to an object. The CUSTOM object +may include version numbers, dependencies, requirements, or any other data +that the application wants to include to describe the file at +TARGETPATH. The application may use this information to guide +download decisions.

DELEGATIONS is an OPTIONAL object and if defined it has the following +format:

{
+  "keys" : {
+      KEYID : KEY,
+      ...
+  },
+  "roles" : [
+    {
+      "name": ROLENAME,
+      "keyids" : [ KEYID, ... ] ,
+      "threshold" : THRESHOLD,
+      ("path_hash_prefixes" : [ HEX_DIGEST, ... ] |
+      "paths" : [ PATHPATTERN, ... ]),
+      "terminating": TERMINATING,
+    },
+    ...
+  ]
+}
+

KEYID and KEY are the same as is described for the + root.json file.

ROLENAME +

THRESHOLD +

A positive integer number of keys (>=1) of that role whose signatures are required in +order to consider a file as being properly signed by that role. See the notes on +THRESHOLD counting in the relevant steps of § 5 Detailed client workflow.

TERMINATING +

A boolean indicating whether subsequent delegations should be considered +if a matching target is not found in this delegation.

As explained in the Diplomat paper +, +terminating delegations instruct the client not to consider future trust +statements that match this delegation’s pattern, which stops the delegation +processing once this delegation (and its descendants) have been processed. +A terminating delegation for a package causes any further statements about a +package that are not made by the delegated party or its descendants to be +ignored.

The "path_hash_prefixes" and "paths" +attributes are OPTIONAL, if used, exactly one of them should be set.

"path_hash_prefixes" +

A list of HEX_DIGESTs used to succinctly describe a set of target +paths. Specifically, each HEX_DIGEST in "path_hash_prefixes" +describes a set of target paths; therefore, "path_hash_prefixes" is +the union over each prefix of its set of target paths. The target paths +must meet this condition: each target path, when hashed with the SHA-256 +hash function to produce a 64-byte hexadecimal digest +(HEX_DIGEST), must share the same prefix as one of the prefixes +in "path_hash_prefixes". This is useful to split a large number of +targets into separate bins identified by consistent hashing.

"paths" +

Some example PATHPATTERNs and expected matches:

+
a PATHPATTERN of "targets/*.tgz" would match file paths +"targets/foo.tgz" and "targets/bar.tgz", but not "targets/foo.txt".
+
+
a PATHPATTERN of "foo-version-?.tgz" matches +"foo-version-2.tgz" and "foo-version-a.tgz", but not +"foo-version-alpha.tgz".
+
+
a PATHPATTERN of "*.tgz" would match "foo.tgz" and "bar.tgz", +but not "targets/foo.tgz"
+
+
a PATHPATTERN of "foo.tgz" would match only "foo.tgz"
+

The metadata files for delegated target roles has the same format as the +top-level targets.json metadata file.

+ +A targets.json example file: + + +

{
+  "signatures": [
+    {
+      "keyid": "135c2f50e57ff11e744d234a62cebad8c38daf399604a7655661cc9199c69164",
+      "sig": "e9fd40008fba263758a3ff1dc59f93e42a4910a282749af915fbbea1401178e5a0
+              12090c228f06db1deb75ad8ddd7e40635ac51d4b04301fce0fd720074e0209"
+    }
+  ],
+  "signed": {
+    "_type": "targets",
+    "spec_version": "1.0.0",
+    "delegations": {
+      "keys": {
+        "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6": {
+          "keytype": "ed25519",
+          "scheme": "ed25519",
+          "keyval": {
+            "public": "b6e40fb71a6041212a3d84331336ecaa1f48a0c523f80ccc762a034c727606fa"
+          }
+        }
+      },
+      "roles": [
+        {
+          "keyids": [
+            "f761033eb880143c52358d941d987ca5577675090e2215e856ba0099bc0ce4f6"
+          ],
+          "name": "project",
+          "paths": [
+            "project/file3.txt"
+          ],
+          "threshold": 1
+        }
+      ]
+    },
+    "expires": "2030-01-01T00:00:00Z",
+    "targets": {
+      "file1.txt": {
+        "hashes": {
+          "sha256": "65b8c67f51c993d898250f40aa57a317d854900b3a04895464313e48785440da"
+        },
+        "length": 31
+      },
+      "dir/file2.txt": {
+        "hashes": {
+          "sha256": "452ce8308500d83ef44248d8e6062359211992fd837ea9e370e561efb1a4ca99"
+        },
+        "length": 39
+      }
+    },
+    "version": 1
+  }
+}
+

4.6. File formats: timestamp.json

Timestamp files will potentially be downloaded very frequently. Unnecessary +information in them will be avoided.

The "signed" portion of timestamp.json is as follows:

{
+  "_type" : "timestamp",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "meta" : METAFILES
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same as is described for the root.json file.

METAFILES is the same as described for the snapshot.json file. In the case +of the timestamp.json file, this MUST only include a description of the +snapshot.json file.

+ +A signed timestamp.json example file: + +

{
+  "signatures": [
+    {
+      "keyid": "1bf1c6e3cdd3d3a8420b19199e27511999850f4b376c4547b2f32fba7e80fca3",
+      "sig": "90d2a06c7a6c2a6a93a9f5771eb2e5ce0c93dd580bebc2080d10894623cfd6eaed
+              f4df84891d5aa37ace3ae3736a698e082e12c300dfe5aee92ea33a8f461f02"
+    }
+  ],
+  "signed": {
+    "_type": "timestamp",
+    "spec_version": "1.0.0",
+    "expires": "2030-01-01T00:00:00Z",
+    "meta": {
+      "snapshot.json": {
+        "hashes": {
+          "sha256": "c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681"
+        },
+        "length": 1007,
+        "version": 1
+      }
+    },
+    "version": 1
+  }
+}
+

4.7. File formats: mirrors.json

The mirrors.json file is signed by the mirrors role. It indicates which +mirrors are active and believed to be mirroring specific parts of the +repository.

The "signed" portion of mirrors.json is as follows:

{
+  "_type" : "mirrors",
+  "spec_version" : SPEC_VERSION,
+  "version" : VERSION,
+  "expires" : EXPIRES,
+  "mirrors" : [
+    { "urlbase" : URLBASE,
+      "metapath" : METAPATH,
+      "targetspath" : TARGETSPATH,
+      "metacontent" : [ PATHPATTERN ... ] ,
+      "targetscontent" : [ PATHPATTERN ... ] ,
+      ("custom" : { ... }) }
+    , ... ]
+}
+

SPEC_VERSION, VERSION and EXPIRES are the same +as is described for the root.json file.

URLBASE +: +
A string giving the URL of the mirror.
+
METAPATH +: +
A string giving the location from which to retrieve metadata files. +METAPATH will be a relative path to URLBASE.
+
TARGETSPATH +: +
A string giving the location from which to retrieve target files. +TARGETSPATH will be a relative path to URLBASE.
+

The lists of PATHPATTERN for "metacontent" and "targetscontent" describe the +metadata files and target files available from the mirror.

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

+
Since it may now be signed using entirely different keys, the client MUST +somehow be able to establish a trusted line of continuity to the latest set +of keys (see § 6.1 Key management and migration). To do so, the client MUST +download intermediate root metadata files, until the latest available one is +reached.
+
+
Let N denote the version number of the trusted root metadata +file.
+
+
Try downloading version N+1 of the root metadata file, up to +some W number of bytes (because the size is unknown). The value for W is set +by the authors of the application using TUF. For example, W may be tens of +kilobytes. The filename used to download the root metadata file is of the +fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is +not available, or we have downloaded more than Y number of root metadata +files (because the exact number is as yet unknown), then go to step 5.3.10. +The value for Y is set by the authors of the application using TUF. For +example, Y may be 2^10.
+
+
Check for an arbitrary software attack. Version N+1 of the root +metadata file MUST have been signed by: (1) a THRESHOLD of keys +specified in the trusted root metadata file (version N), and (2) a +THRESHOLD of keys specified in the new root metadata file being +validated (version N+1). When computing the THRESHOLD each +KEY MUST only contribute one SIGNATURE. That is, each +SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified +SIGNATURE from that KEYID towards the THRESHOLD. +If version N+1 is not signed as required, discard it, abort the update cycle, +and report the signature failure. On the next update cycle, begin at step +§ 5.3 Update the root role and version N of the root metadata file.
+
+
Check for a rollback attack. The version number of the new root +metadata (version N+1) MUST be exactly the version in the trusted root +metadata (version N) incremented by one, that is precisely N+1. +If the version of the new root metadata file is not N+1, discard it, +abort the update cycle, and report the rollback attack.
+
+
Note that the expiration of the new (intermediate) root metadata +file does not matter yet, because we will check for it in step 5.3.10.
+
+
Set the trusted root metadata file to the new root metadata +file.
+
+
Persist root metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. root.json).
+
+
Repeat steps 5.3.2 to 5.3.9
+
+
Check for a freeze attack. The expiration timestamp in the +trusted root metadata file MUST be higher than the fixed update start time. +If the trusted root metadata file has expired, abort the update cycle, +report the potential freeze attack.
+
+
If the timestamp and / or snapshot keys have been rotated, then delete the +trusted timestamp and snapshot metadata files. This is done +in order to recover from fast-forward attacks after the repository has been +compromised and recovered. A fast-forward attack happens when attackers +arbitrarily increase the version numbers of: (1) the timestamp metadata, (2) +the snapshot metadata, and / or (3) the targets, or a delegated targets, +metadata file in the snapshot metadata. Please see the Mercury +paper +for more details.
+
+
Set whether consistent snapshots are used as per the trusted + root metadata file (see § 4.3 File formats: root.json).
+

5.4. Update the timestamp role

+
Download the timestamp metadata file, up to X number of bytes +(because the size is unknown). The value for X is set by the authors of the +application using TUF. For example, X may be tens of kilobytes. The filename +used to download the timestamp metadata file is of the fixed form FILENAME.EXT +(e.g., timestamp.json).
+
+
Check for an arbitrary software attack. The new timestamp +metadata file MUST have been signed by a THRESHOLD of keys specified +in the trusted root metadata file. When computing the THRESHOLD each +KEY MUST only contribute one SIGNATURE. That is, each +SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified +SIGNATURE from that KEYID towards the THRESHOLD. If the +new timestamp metadata file is not properly signed, discard it, abort the +update cycle, and report the signature failure.
+
+
Check for a rollback attack.
+
1. +
  The version number of the trusted timestamp metadata file, if +any, MUST be less than the version number of the new timestamp +metadata file. If the new timestamp metadata version is less than the trusted +timestamp metadata version, discard it, abort the update cycle, and +report the potential rollback attack. In case they are equal, discard the new +timestamp metadata and abort the update cycle. This is normal and it +shouldn’t raise any error. The reason for aborting the update process is that +there shouldn’t be any changes in the content of this, or any other metadata +files too, considering it has the same version as the already trusted one.
  +
2. +
  The version number of the snapshot metadata file in the +trusted timestamp metadata file, if any, MUST be less than or equal to its +version number in the new timestamp metadata file. If not, discard the new +timestamp metadata file, abort the update cycle, and report the failure.
  +
+
+
Check for a freeze attack. The expiration timestamp in the +new timestamp metadata file MUST be higher than the fixed update start time. +If so, the new timestamp metadata file becomes the trusted timestamp +metadata file. If the new timestamp metadata file has expired, discard it, +abort the update cycle, and report the potential freeze attack.
+
+
Persist timestamp metadata. The client MUST write the file +to non-volatile storage as FILENAME.EXT (e.g. timestamp.json).
+

5.5. Update the snapshot role

+
Download snapshot metadata file, up to either the number of bytes +specified in the timestamp metadata file, or some Y number of bytes. The value +for Y is set by the authors of the application using TUF. For example, Y may be +tens of kilobytes. If consistent snapshots are not used (see +Section § 6.2 Consistent snapshots), then the filename used to download the +snapshot metadata file is of the fixed form FILENAME.EXT (e.g., +snapshot.json). Otherwise, the filename is of the form +VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER is +the version number of the snapshot metadata file listed in the timestamp +metadata file.
+
+
Check against timestamp role’s snapshot hash. The hashes +of the new snapshot metadata file MUST match the hashes, if any, listed in +the trusted timestamp metadata. This is done, in part, to prevent a +mix-and-match attack by man-in-the-middle attackers. It is safe to check the +hashes before the signatures, because the hashes come from the timestamp +role, which we have already verified in the previous step; it is also a quick +way to reject bad metadata. If the hashes do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new snapshot +metadata file MUST have been signed by a THRESHOLD of keys specified in +the trusted root metadata file. When computing the THRESHOLD each +KEY MUST only contribute one SIGNATURE. That is, each +SIGNATURE which is counted towards the THRESHOLD MUST have +a unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified +SIGNATURE from that KEYID towards the THRESHOLD. If the +new snapshot metadata file is not signed as required, discard it, abort the +update cycle, and report the signature failure.
+
+
Check against timestamp role’s snapshot version. The version +number of the new snapshot metadata file MUST match the version number listed +in the trusted timestamp metadata. If the versions do not match, discard the +new snapshot metadata, abort the update cycle, and report the failure.
+
+
Check for a rollback attack. The version number of the targets +metadata file, and all delegated targets metadata files, if any, in the +trusted snapshot metadata file, if any, MUST be less than or equal to its +version number in the new snapshot metadata file. Furthermore, any targets +metadata filename that was listed in the trusted snapshot metadata file, if +any, MUST continue to be listed in the new snapshot metadata file. If any of +these conditions are not met, discard the new snapshot metadata file, abort +the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new snapshot metadata file MUST be higher than the fixed update start time. +If so, the new snapshot metadata file becomes the trusted snapshot metadata +file. If the new snapshot metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist snapshot metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. snapshot.json).
+

5.6. Update the targets role

+
Download the top-level targets metadata file, up to either the +number of bytes specified in the snapshot metadata file, or some Z number of +bytes. The value for Z is set by the authors of the application using TUF. For +example, Z may be tens of kilobytes. If consistent snapshots are not used (see +§ 6.2 Consistent snapshots), then the filename used to download the targets +metadata file is of the fixed form FILENAME.EXT (e.g., targets.json). +Otherwise, the filename is of the form VERSION_NUMBER.FILENAME.EXT (e.g., +42.targets.json), where VERSION_NUMBER is the version number of the targets +metadata file listed in the snapshot metadata file.
+
+
Check against snapshot role’s targets hash. The hashes +of the new targets metadata file MUST match the hashes, if any, listed in the +trusted snapshot metadata. This is done, in part, to prevent a mix-and-match +attack by man-in-the-middle attackers. It is safe to check the hashes before +the signatures, because the hashes come from the snapshot role, which we have +already verified in the previous step; it is also a quick way to reject bad +metadata. If the new targets metadata file does not match, discard the new +target metadata, abort the update cycle, and report the failure.
+
+
Check for an arbitrary software attack. The new targets +metadata file MUST have been signed by a THRESHOLD of keys specified +in the trusted root metadata file. When computing the THRESHOLD each +KEY MUST only contribute one SIGNATURE. That is, each +SIGNATURE which is counted towards the THRESHOLD MUST have a +unique KEYID. Even if a KEYID is listed more than once in the +"signatures" list a client MUST NOT count more than one verified +SIGNATURE from that KEYID towards the THRESHOLD. If the +new targets metadata file is not signed as required, discard it, abort the +update cycle, and report the failure.
+
+
Check against snapshot role’s targets version. The version +number of the new targets metadata file MUST match the version number listed +in the trusted snapshot metadata. If the versions do not match, discard it, +abort the update cycle, and report the failure.
+
+
Check for a freeze attack. The expiration timestamp in the +new targets metadata file MUST be higher than the fixed update start time. +If so, the new targets metadata file becomes the trusted targets metadata +file. If the new targets metadata file is expired, discard it, abort the +update cycle, and report the potential freeze attack.
+
+
Persist targets metadata. The client MUST write the file to +non-volatile storage as FILENAME.EXT (e.g. targets.json).
+
+
Perform a pre-order depth-first search for metadata about the +desired target, beginning with the top-level targets role. Note: If +any metadata requested in steps 5.6.7.1 - 5.6.7.2 cannot be downloaded nor +validated, end the search and report that the target cannot be found.
+
1. +
  If this role has been visited before, then skip this role + (so that cycles in the delegation graph are avoided). Otherwise, if an + application-specific maximum number of roles have been visited, then go to + step § 5.7 Fetch target (so that attackers cannot cause the client to waste excessive + bandwidth or time). Otherwise, if this role contains metadata about the + desired target, then go to step § 5.7 Fetch target.
  +
2. +
  Otherwise, recursively search the list of delegations in + order of appearance.
  +
  1. +
    If the current delegation is a terminating delegation, + then jump to step § 5.7 Fetch target.
    +
  2. +
    Otherwise, if the current delegation is a + non-terminating delegation, continue processing the next delegation, if + any. Stop the search, and jump to step § 5.7 Fetch target as soon as a delegation + returns a result.
    +
  +
+

5.7. Fetch target

+
Verify the desired target against its targets metadata.
+
+
If there is no targets metadata about this target, abort the + update cycle and report that there is no such target.
+
+
Otherwise, download the target (up to the number of bytes + specified in the targets metadata), and verify that its hashes match the + targets metadata. (We download up to this number of bytes, because in some + cases, the exact number is unknown. This may happen, for example, if an + external program is used to compute the root hash of a tree of targets files, + and this program does not provide the total size of all of these files.) If + consistent snapshots are not used (see § 6.2 Consistent snapshots), then the + filename used to download the target file is of the fixed form FILENAME.EXT + (e.g., foobar.tar.gz). Otherwise, the filename is of the form + HASH.FILENAME.EXT (e.g., + c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz), + where HASH is one of the hashes of the targets file listed in the targets + metadata file found earlier in step § 5.6 Update the targets role. In either + case, the client MUST write the file to non-volatile storage as FILENAME.EXT.
+

6. Repository operations

See https://theupdateframework.io/ for +discussion of recommended usage in various situations.

6.1. Key management and migration

To replace a delegated developer key, the role that delegated to that key +just replaces that key with another in the signed metadata where the +delegation is done.

6.2. Consistent snapshots

6.2.1. Writing consistent snapshots

We now explain how a repository should write metadata and targets to +produce self-contained consistent snapshots.

6.2.2. Reading consistent snapshots

See § 5 Detailed client workflow for more details.

6.3. Adding and updating targets

The following subsections describe how to update metadata on the repository +when adding targets to the repository, or updating existing targets.

6.3.1. Update targets metadata

+
Add the new (or update an existing) TARGETS object + in the relevant targets metadata (either the top-level targets metadata, or + a delegated targets metadata).
+
+
Increment the VERSION number in the updated targets + metadata.
+
+
Sign the updated targets metadata with at least a THRESHOLD of keys + for the associated targets role (either the top-level targets role, or a + delegated targets role).
+
+
Write the updated targets metadata, ensuring the targets metadata filename is + prefixed with the VERSION number if consistent snapshots + are enabled for the repository.
+

6.3.2. Update snapshot metadata

+
Update the VERSION number and, when in use, + LENGTH and HASHES for any targets + metadata modified during § 6.3.1 Update targets metadata within the + METAFILES object of the snapshot metadata.
+
+
Increment the VERSION number of the snapshot metadata.
+
+
Sign the snapshot metadata with at least a THRESHOLD of keys for the + snapshot role.
+
+
Write the updated snapshot metadata, ensuring the snapshot metadata filename + is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

6.3.3. Update timestamp metadata

+
Update the VERSION and, when in use, the + LENGTH and HASHES for the + snapshot metadata within the METAFILES object of the timestamp + metadata.
+
+
Increment the VERSION number of the timestamp metadata.
+
+
Sign the timestamp metadata with at least a THRESHOLD of keys for the + timestamp role.
+
+
Write the updated timestamp metadata, ensuring the timestamp metadata + filename is prefixed with the VERSION number if consistent + snapshots are enabled for the repository.
+

7. Future directions and open questions

7.1. Support for bogus clocks

The framework may need to offer an application-enablable "no, my clock is +supposed to be wrong" mode, since others have noticed that many users seem +to have incorrect clocks.

Index

Terms defined by this specification

CONSISTENT_SNAPSHOT, in § 4.3 +
CUSTOM, in § 4.5 +
date-time, in § 4.2.3 +
DELEGATIONS, in § 4.5 +
"ecdsa", in § 4.2.2 +
"ecdsa-sha2-nistp256", in § 4.2.2 +
+ "ed25519" +
- dfn for keytype, in § 4.2.2 +
- dfn for scheme, in § 4.2.2 +
+
EXPIRES, in § 4.3 +
HASH, in § 4.4 +
+ HASHES +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
HEX_DIGEST, in § 4.5 +
KEY, in § 4.2.2 +
+ KEYID +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
KEYTYPE, in § 4.2.2 +
KEYVAL, in § 4.2.2 +
+ LENGTH +
- dfn for metapath, in § 4.4 +
- dfn for targets-obj, in § 4.5 +
+
METAFILES, in § 4.4 +
+ METAPATH +
- dfn for mirrors, in § 4.7 +
- dfn for snapshot, in § 4.4 +
+
mirrors.json, in § 4.7 +
"path_hash_prefixes", in § 4.5 +
PATHPATTERN, in § 4.5 +
"paths", in § 4.5 +
+ PUBLIC +
- dfn for keyval-ecdsa, in § 4.2.2 +
- dfn for keyval-ed25519, in § 4.2.2 +
- dfn for keyval-rsa, in § 4.2.2 +
+
+ ROLE +
- dfn for role, in § 4.2.1 +
- dfn for root, in § 4.3 +
+
ROLENAME, in § 4.5 +
root.json, in § 4.3 +
"rsa", in § 4.2.2 +
"rsassa-pss-sha256", in § 4.2.2 +
SCHEME, in § 4.2.2 +
SIGNATURE, in § 4.2.1 +
snapshot.json, in § 4.4 +
SPEC_VERSION, in § 4.3 +
TARGETPATH, in § 4.5 +
TARGETS, in § 4.5 +
targets.json, in § 4.5 +
TARGETSPATH, in § 4.7 +
TERMINATING, in § 4.5 +
THRESHOLD, in § 4.5 +
timestamp.json, in § 4.6 +
URLBASE, in § 4.7 +
+ VERSION +
- dfn for metapath, in § 4.4 +
- dfn for role, in § 4.3 +
+

The Update Framework Specification

The Update Framework Specification

Version: 1.0.17 Last modified: 11 December 2020

1. Introduction

1.1. Scope

1.2. Motivation

1.3. History and credit

1.4. Non-goals

1.5. Goals

1.5.1. Goals for implementation

1.5.2. Goals to protect against specific attacks

1.5.3. Goals for PKI

1.5.4. TUF Augmentation Proposal (TAP) support

2. System overview

2.1. Roles and PKI

2.1.1. Root role

2.1.2. Targets role

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

3.1.1. Target files

3.1.2. Metadata files

3.1.2.1. Metadata files for targets delegation

4. Document formats

4.1. Metaformat

4.2. File formats: general principles

4.3. File formats: root.json

4.4. File formats: snapshot.json

4.5. File formats: targets.json and delegated target roles

4.6. File formats: timestamp.json

4.7. File formats: mirrors.json

5. Detailed client workflow

5.1. Record fixed update start time

5.2. Load trusted root metadata

5.3. Update the root role

5.4. Update the timestamp role

5.5. Update the snapshot role

5.6. Update the targets role

5.7. Fetch target

6. 6. Usage

6.1. Key management and migration

7. Consistent Snapshots

7.1. Writing consistent snapshots

7.2. Reading consistent snapshots

8. Future directions and open questions

8.1. Support for bogus clocks

Index

Terms defined by this specification

The Update Framework Specification

Version: 1.0.17 Last modified: 11 December 2020

1. Introduction

1.1. Scope

1.2. Motivation

1.3. History and credit

1.4. Non-goals

1.5. Goals

1.5.1. Goals for implementation

1.5.2. Goals to protect against specific attacks

1.5.3. Goals for PKI

1.5.4. TUF Augmentation Proposal (TAP) support

2. System overview

2.1. Roles and PKI

2.1.1. Root role

2.1.2. Targets role

2.1.3. Snapshot role

2.1.4. Timestamp role

2.1.5. Mirrors role

2.2. Threat model and analysis

2.3. Protocol, Operations, Usage, and Format (POUF) documents

3. The repository

3.1. Repository layout

3.1.1. Target files

3.1.2. Metadata files

3.1.2.1. Metadata files for targets delegation

4. Document formats

4.1. Metaformat

Version: 1.0.17
Last modified: 11 December 2020

Version: 1.0.17
Last modified: 11 December 2020

Version: 1.0.17
Last modified: 11 December 2020