diff --git a/README.md b/README.md index 70672ecd3a..0ce469d434 100644 --- a/README.md +++ b/README.md @@ -58,13 +58,12 @@ by various tech companies and open source organizations. A variant of TUF called [Uptane](https://uptane.github.io/) is used to secure over-the-air updates in automobiles. -Please see the [TUF Introduction](docs/OVERVIEW.rst) and -[TUF's website](https://theupdateframework.com/) for more information about TUF! +Please see [TUF's website](https://theupdateframework.com/) for more information about TUF! Documentation ------------- -* [Introduction to TUF's Design](docs/OVERVIEW.rst) +* [Introduction to TUF's Design](https://theupdateframework.io/overview/) * [The TUF Specification](https://theupdateframework.github.io/specification/latest/) * Examples: [client](examples/client_example) and [repository](examples/repo_example) * [API Reference](https://theupdateframework.readthedocs.io/) diff --git a/docs/GETTING_STARTED.rst b/docs/GETTING_STARTED.rst index fad0d847fb..f958373975 100644 --- a/docs/GETTING_STARTED.rst +++ b/docs/GETTING_STARTED.rst @@ -1,7 +1,7 @@ Getting Started --------------- -- `Overview of TUF `_ +- `Overview of TUF `_ - `Installation `_ - Beginner Tutorials (using the basic command-line interface): - `Quickstart `_ diff --git a/docs/METADATA.md b/docs/METADATA.md deleted file mode 100644 index 9f140fe8fe..0000000000 --- a/docs/METADATA.md +++ /dev/null @@ -1,91 +0,0 @@ -# Metadata - -Metadata files provide information that clients can use to make update decisions. Different metadata files provide different information. The various metadata files are signed by different keys as are indicated by the root role. The concept of roles allows TUF to only trust information that a role is trusted to provide. - -The signed metadata files always include the time they were created and their expiration dates. This ensures that outdated metadata will be detected and that clients can refuse to accept metadata older than that which they've already seen. - -All TUF metadata uses a subset of the JSON object format. When calculating the digest of an object, we use the [Canonical JSON](http://wiki.laptop.org/go/Canonical_JSON) format. Implementation-level detail about the metadata can be found in the [spec](docs/tuf-spec.txt). - -There are four required top-level roles and one optional top-level role, each with their own metadata file. - -Required: - -* Root -* Targets -* Snapshot -* Timestamp - -Optional: - -* Mirrors (unimplemented) - -There may also be any number of delegated target roles. - -## Root Metadata (root.json) - -Signed by: Root role. - -Specifies the other top-level roles. When specifying these roles, the trusted keys for each role are listed along with the minimum number of those keys which are required to sign the role's metadata. We call this number the signature threshold. - -See [example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/root.json) of Root metadata. - -## Targets Metadata (targets.json) - -Signed by: Targets role. - -The targets.json metadata file lists hashes and sizes of target files. Target files are the actual files that clients are intending to download (for example, the software updates they are trying to obtain). - -This file can optionally define other roles to which it delegates trust. Delegating trust means that the delegated role is trusted for some or all of the target files available from the repository. When delegated roles are specified, they are specified in a similar way to how the Root role specifies the top-level roles: the trusted keys and signature threshold for each role is given. Additionally, one or more patterns are specified which indicate the target file paths for which clients should trust each delegated role. - -See [example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/targets.json) of Targets metadata. - -## Delegated Targets Metadata (role1.json) - -Signed by: A delegated targets role. - -The metadata files provided by delegated targets roles follow exactly the same format as the metadata file provided by the top-level Targets role. - -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.json - -where DELEGATED_ROLE is the name of the delegated role that has been specified in targets.json. If this role further delegates trust to a role named ANOTHER_ROLE, that role's signed metadata file is made available at: - -/ANOTHER_ROLE.json - -See -[example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/role1.json) -of delegated Targets metadata and [example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/role2.json) of a nested delegation. - -## snapshot Metadata (snapshot.json) - -Signed by: Snapshot role. - -The snapshot.json metadata file lists the version, and optionally the file hashes and sizes, of the top-level targets metadata and all delegated targets metadata. This file ensures that clients will see a consistent view of the files on the repository. That is, metadata files (and thus target file) that existed on the repository at different times cannot be combined and presented to clients by an attacker. - -​See [example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/snapshot.json) of Snapshot metadata. - -## Timestamp Metadata (timestamp.json) - -Signed by: Timestamp role. - -The timestamp.json metadata file lists the hashes and size of the snapshot.json file. This is the first and potentially only file that needs to be downloaded when clients poll for the existence of updates. This file is frequently resigned and has a short expiration date, thus allowing clients to quickly detect if they are being prevented from obtaining the most recent metadata. An online key is generally used to automatically resign this file at regular intervals. - -There are two primary reasons why the timestamp.json file doesn't contain all of the information that the snapshot.json file does. - -* The timestamp.json file is downloaded very frequently and so should be kept as small as possible, especially considering that the snapshot.json file grows in size in proportion to the number of delegated target roles. -* As the Timestamp role's key is an online key and thus at high risk, separate keys should be used for signing the snapshot.json metadata file so that the Snapshot role's keys can be kept offline and thus more secure. - -See [example](https://raw.githubusercontent.com/theupdateframework/tuf/develop/tests/repository_data/repository/metadata/timestamp.json) of Timestamp metadata. - -## Mirrors Metadata (mirrors.json) - -Optionally signed by: Mirrors role. - -The mirrors.json file provides an optional way to provide mirror list updates to TUF clients. Mirror lists can alternatively be provided directly by the software update system and obtained in any way the system sees fit, including being hard coded if that is what an applications wants to do. - -No example available. At the time of writing, this hasn't been implemented in -TUF. Currently mirrors are specified by the client code. diff --git a/docs/OVERVIEW.rst b/docs/OVERVIEW.rst deleted file mode 100644 index 44f942c652..0000000000 --- a/docs/OVERVIEW.rst +++ /dev/null @@ -1,120 +0,0 @@ -What Is a Software Update System? ---------------------------------- - -Generally, a software update system is an application (or part of an -application) running on a client system that obtains and installs -software. These systems typically update the applications installed -on client systems to introduce new features, enhancements, and security -fixes. - -Three major classes of software update systems are: - -- **Application updaters** which are used by applications to update - themselves. For example, Firefox updates itself through its own - application updater. - -- **Library package managers** such as those offered by many - programming languages for installing additional libraries. These are - systems such as Python's pip/easy_install + PyPI, Perl's CPAN, - Ruby's RubyGems, and PHP's Composer. - -- **System package managers** used by operating systems to update and - install all of the software on a client system. Debian's APT, Red - Hat's YUM, and openSUSE's YaST are examples of these. - -Our Approach ------------- - -There are literally thousands of different software update systems in -common use today. (In fact the average Windows user has about `two -dozen `_ -different software updaters on their machine!) - -We are building a library that can be universally (and in most cases -transparently) used to secure software update systems. - -Overview --------- - -On the surface, the update procedure followed by a software update system can be regarded -as straightforward. Obtaining and installing an update just means: - -- Knowing when an update exists. -- Downloading the update. -- Applying the changes introduced by the update. - -The problem with this view is that it is only straightforward when there -are no malicious parties involved throughout the update procedure. If an attacker -is trying to interfere with these seemingly simple steps, there is plenty -that they can do. - -TUF is designed to perform the first two steps of the above update procedure, -while guarding against the majority of attacks that malicious actors have at -their disposal; especially those attacks that are overlooked by security-conscious -developers. - - -Background ----------- - -Let's assume you take the approach that most systems do (at least, the -ones that even try to be secure). You download both the file you want -and a cryptographic signature of the file. You already know which key -you trust to make the signature. You check that the signature is correct -and was made by this trusted key. All seems well, right? Wrong. You are -still at risk in many ways, including: - -- An attacker keeps giving you the same file, so you never realize - there is an update. -- An attacker gives you an older, insecure version of a file that you - already have, so you download that one and blindly use it thinking - it's newer. -- An attacker gives you a newer version of a file you have but it's not - the newest one. It's newer to you, but it may be insecure and - exploitable by the attacker. -- An attacker compromises the key used to sign these files and now you - download a malicious file that is properly signed. - -These are just some of the attacks software update systems are -vulnerable to when only using signed files. See -`Security `_ for a full list of attacks and updater -weaknesses TUF is designed to prevent. - -The following papers provide detailed information on securing software -updater systems, TUF's design and implementation details, attacks on -package managers, and package management security: - -- `Mercury: Bandwidth-Effective Prevention of Rollback Attacks Against Community Repositories - ` - -- `Diplomat: Using Delegations to Protect Community Repositories - ` - -- `Survivable Key Compromise in Software Update - Systems ` - -- `A Look In the Mirror: Attacks on Package - Managers ` - -- `Package Management - Security ` - -What TUF Does -------------- - -In order to securely download and verify target files, TUF requires a -few extra files to exist on a repository. These are called metadata -files. TUF metadata files contain additional information, including -information about which keys are trusted, the cryptographic hashes of -files, signatures on the metadata, metadata version numbers, and the -date after which the metadata should be considered expired. - -When a software update system using TUF wants to check for updates, it -asks TUF to do the work. That is, your software update system never has -to deal with this additional metadata or understand what's going on -underneath. If TUF reports back that there are updates available, your -software update system can then ask TUF to download these files. TUF -downloads them and checks them against the TUF metadata that it also -downloads from the repository. If the downloaded target files are -trustworthy, TUF hands them over to your software update system. See -`Metadata `_ for more information and examples. diff --git a/docs/SECURITY.md b/docs/SECURITY.md deleted file mode 100644 index 8535acd3ef..0000000000 --- a/docs/SECURITY.md +++ /dev/null @@ -1,76 +0,0 @@ -# Security - -Generally, a software update system is secure if it can be sure that it knows about the latest available updates in a timely manner, any files it downloads are the correct files, and no harm results from checking or downloading files. The details of making this happen are complicated by various attacks that can be carried out against software update systems. - -## Attacks and Weaknesses - -The following are some of the known attacks on software update systems, including weaknesses that make attacks possible. In order to design a secure software update framework, these need to be understood and protected against. Some of these issues are or can be related depending on the design and implementation of a software update system. - -* **Arbitrary software installation**. An attacker installs anything they want on the client system. That is, an attacker can provide arbitrary files in response to download requests and the files will not be detected as illegitimate. - -* **Rollback attacks**. An attacker presents a software update system with older files than those the client has already seen, causing the client to use files older than those the client knows about. - -* **Fast-forward attacks**. An attacker arbitrarily increases the version numbers of project metadata files in the snapshot -metadata well beyond the current value, 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 could 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 continues to present a software update system with the same files the client has already seen. The result is that the client does not know that new files are available. - -* **Endless data attacks**. An attacker responds to a file download request with an endless stream of data, causing harm to clients (e.g. a disk partition filling up or memory exhaustion). - -* **~~Slow retrieval attacks~~**. An attacker responds to clients with a very slow stream of data that essentially results in the client never continuing the update process.\ -**_NOTE: Due to limitations in a 3rd-party HTTP library, the TUF reference implementation currently provides only limited protection against slow retrieval attacks (see [tuf#932](https://github.com/theupdateframework/python-tuf/issues/932)). We plan to fix this in a future release._** - -* **Extraneous dependencies attacks**. An attacker indicates to clients that in order to install the software they wanted, they also need to install unrelated software. This unrelated software can be from a trusted source but may have known vulnerabilities that are exploitable by the attacker. - -* **Mix-and-match attacks**. An attacker presents clients with a view of a repository that includes files that did not exist together on the repository at the same time. This can result in, for example, outdated versions of dependencies being installed. - -* **Wrong software installation**. An attacker provides a client with a trusted file that is not the one the client wanted. - -* **Malicious mirrors preventing updates**. An attacker in control of one repository mirror is able to prevent users from obtaining updates from other, good mirrors. - -* **Vulnerability to key compromises**. An attacker who is able to compromise a single key or less than a given threshold of keys can compromise clients. This includes relying on 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). - -## Design Concepts - -The design and implementation of TUF aims to be secure against all of the above attacks. A few general ideas drive much of the security of TUF. - -For the details of how TUF conveys the information discussed below, see the [Metadata documentation](METADATA.md). - -## Trust - -Trusting downloaded files really means trusting that the files were provided by some trusted party. Two frequently overlooked aspects of trust in a secure software update system are: - -* Trust should not be granted forever. Trust should expire if it is not renewed. -* Compartmentalized trust. A trusted party should only be trusted for files that it is supposed to provide. - -## Mitigated Key Risk - -Cryptographic signatures are a necessary component in securing a software update system. The safety of the keys that are used to create these signatures affects the security of clients. Rather than incorrectly assume that private keys are always safe from compromise, a secure software update system must strive to keep clients as safe as possible even when compromises happen. - -Keeping clients safe despite dangers to keys involves: - -* Fast and secure key replacement and revocation. -* Minimally trusting keys that are at high risk. Keys that are kept online or used in an automated fashion shouldn't pose immediate risk to clients if compromised. -* Supporting the use of multiple keys with threshold/quorum signatures trust. - -## Integrity - -File integrity is important both with respect to single files as well as collections of files. It's fairly obvious that clients must verify that individual downloaded files are correct. Not as obvious but still very important is the need for clients to be certain that their entire view of a repository is correct. For example, if a trusted party is providing two files, a software update system should see the latest versions of both of those files, not just one of the files and not versions of the two files that were never provided together. - -## Freshness - -As software updates often fix security bugs, it is important for software update systems to be able to obtain the latest versions of files that are available. An attacker may want to trick a client into installing outdated versions of software or even just convince a client that no updates are available. - -Ensuring freshness means to: - -* Never accept files older than those that have been seen previously. -* Recognize when there may be a problem obtaining updates. - -Note that it won't always be possible for a client to successfully update if an attacker is responding to their requests. However, a client should be able to recognize that updates may exist that they haven't been able to obtain. - -## Implementation Safety - -In addition to a secure design, TUF also works to be secure against implementation vulnerabilities including those common to software update systems. In some cases this is assisted by the inclusion of additional information in metadata. For example, knowing the expected size of a target file that is to be downloaded allows TUF to limit the amount of data it will download when retrieving the file. As a result, TUF is secure against endless data attacks (discussed above). diff --git a/docs/TAP.rst b/docs/TAP.rst deleted file mode 100644 index 3c20fde4f0..0000000000 --- a/docs/TAP.rst +++ /dev/null @@ -1,12 +0,0 @@ -What is a TAP? --------------- - -A TAP (TUF Augmentation Proposal) is a design document providing information to -the TUF community, or describing a new feature for TUF or its processes or -environment. We intend TAPs to be the primary mechanisms for proposing major -new features, for collecting community input on an issue, and for documenting -the design decisions that have gone into TUF. - -Please visit the `TAPs GitHub repo `_ -to review design changes that have been proposed to date, or to submit -your own new feature. diff --git a/docs/conf.py b/docs/conf.py index a5314127e8..4577404ba3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['GETTING_STARTED.rst', 'OVERVIEW.rst', 'TAP.rst'] +exclude_patterns = ['GETTING_STARTED.rst'] # -- Options for HTML output ------------------------------------------------- diff --git a/tuf/ATTACKS.md b/tuf/ATTACKS.md index f76cf0b4c3..416e164ddb 100644 --- a/tuf/ATTACKS.md +++ b/tuf/ATTACKS.md @@ -319,5 +319,5 @@ SlowRetrievalError exception to the client application. ## Conclusion ## These are just some of the attacks that TUF provides protection against. For more attacks and updater weaknesses, please see the -[Security](https://github.com/theupdateframework/python-tuf/blob/develop/docs/SECURITY.md) +[Security](https://theupdateframework.io/security/) page.