Merge branch 'repository-tools' of https://github.com/theupdateframework/tuf into repository-tools

METADATA.md

@@ -0,0 +1,81 @@
+# 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 roles. 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
+* Release
+* Timestamp 
+
+Optional:
+
+* Mirrors 
+
+There may also be any number of delegated target roles.
+
+## Root Metadata (root.txt)
+
+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](http://mirror1.poly.edu/test-pypi/metadata/root.txt).
+
+## Targets Metadata (targets.txt)
+
+Signed by: Targets role.
+
+The targets.txt 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](http://mirror1.poly.edu/test-pypi/metadata/targets.txt).
+
+## Delegated Targets Metadata (targets/foo.txt)
+
+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.
+
+The location of the metadata file for each delegated target role is based on the delegation ancestry of the role. If the top-level Targets role defines a role named foo, then the delegated target role's full name would be targets/foo and its metadata file will be available on the repository at the path targets/foo.txt (this is relative to the base directory from which all metadata is available). This path is just the full name of the role followed by a file extension.
+
+If this delegated role foo further delegates to a role bar, then the result is a role whose full name is targets/foo/bar and whose signed metadata file is made available on the repository at targets/foo/bar.txt.
+
+See [example](http://mirror1.poly.edu/test-pypi/metadata/targets/unclaimed.txt).
+
+## Release Metadata (release.txt)
+
+Signed by: Release role.
+
+The release.txt metadata file lists hashes and sizes of all metadata files other than timestamp.txt. 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](http://mirror1.poly.edu/test-pypi/metadata/release.txt).
+
+## Timestamp Metadata (timestamp.txt)
+
+Signed by: Timestamp role.
+
+The timestamp.txt metadata file lists the hashes and size of the release.txt 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 that the timestamp.txt file doesn't contain all of the information that the release.txt file does.
+
+* The timestamp.txt file is downloaded very frequently and so should be kept as small as possible, especially considering that the release.txt 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 release.txt metadata file so that the Release role's keys can be kept offline and thus more secure.
+
+See [example](http://mirror1.poly.edu/test-pypi/metadata/timestamp.txt).
+
+## Mirrors Metadata (mirrors.txt)
+
+Optionally signed by: Mirrors role.
+
+The mirrors.txt 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. 

README.md

@@ -30,7 +30,7 @@ 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
+use today. (In fact the average Windows user has about [two dozen](http://secunia.com/gfx/pdf/Secunia_RSA_Software_Portfolio_Security_Exposure.pdf) different
 software updaters on their machine!)
 
 We are building a library that can be universally (and in most cases

SECURITY.md

@@ -0,0 +1,69 @@
+#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. 
+
+* **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. 
+
+* **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 never existed 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**. At 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 that software update systems 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).