|0.3.0-beta3||Nov 30, 2021|
|0.3.0-beta1||Oct 8, 2021|
|0.3.0-alpha3||Sep 6, 2017|
|0.3.0-alpha1||Jul 29, 2017|
#177 in Cryptography
21 downloads per month
A Rust implementation of The Update Framework (TUF).
Full documentation is hosted at docs.rs.
This is under active development and may not suitable for production use. Further, the API is unstable and you should be prepared to refactor on even patch releases.
Please make all pull requests to the
This project has a full disclosure policy on security related errors. Please treat these errors like all other bugs and file a public issue. Errors communicated via other channels will be immediately made public.
This crate provides an API for talking to repositories that implement The Update Framework (TUF).
If you are unfamiliar with TUF, you should read up on it via the official
website. This crate aims to implement the entirety of
the specification as defined at the head of the
branch in the
official TUF git repository.
Additionally, the following two papers are valuable supplements in understanding how to actually implement TUF for a community repository.
Failure to read the spec and the above papers will likely lead to an implementation that does not take advantage of all the security guarantees that TUF offers.
It should be noted that historically the TUF spec defined exactly one metadata format and one
way of organizing metadata within a repository. Thus, all TUF implementation could perfectly
interoperate. The TUF spec has moved to describing how a framework should behave leaving many
of the detais up to the implementor. Therefore, there are zero guarantees that this library
will work with any other TUF implementation. Should you want to access a TUF repository that
rust-tuf as its backend from another language, ASN.1 modules and metadata schemas are
provided that will allow you to interoperate with this library.
Part of TUF is that it acts as its own PKI, and there is no integration that needs to be done for managing keys.
Note: No two private keys that are generated should ever exist on the same hardware. When a
step says "generate
N keys," the implication is that these
N keys are generated on
The first set of keys that need to be generated at the root keys that are used to sign the root metadata. The root should be defined with the following properties:
- 3 keys
- threshold of 2
- 5 keys
- threshold of 3
If a threshold of root keys are compromised, then the entire system is compromised and TUF
clients will need to be manually updated. Similarly, if some
X keys are lost such that the
N cannot be reached, then clients will also need to be manually updated. Both of
situations are considered critically unsafe. Whatever number of keys are used, it should be
assumed that some small number may be lost or compromised.
These root keys MUST be kept offline on secure media.
TUF's most useful feature is the ability to delegate certain roles to sign certain targets. This is discussed in extensive detail in the aforementioned Diplomat paper. There are three problems faced when delegating trust in TUF:
- What to do for existent accounts that have not yet created and signed TUF metadata
- What to do when a new account registers
- What to do when an account uploads a new target and new metadata
There are several approaches for dealing with the above scenarios. We are only going to discuss on here as it is the recommended approach. This approach is taken directly from Section 6.1 of the Diplomat paper
The top-level targets role delegates to three other roles and are listed in the following order:
- Delegates to project-specific roles that have registered keys with TUF
- Signs all packages for all projects that have been "abandoned" or left unupdated for a long time AND have not yet registered keys with TUF
- Signs all packages for all new projects as well as projects that were relegated to
targets role as well as
MUST all use offline keys.
The critical, manual step is to register new projects with TUF keys and move them into the
claimed-projects role. Projects that refuse to register keys should have their packages
periodically moved into the
rarely-updated-projects role. Projects in either of these two
roles are safe from compromise as their keys are offline. Since the keys used for the above
operation are kept offline, this is periodic, manual process.
In a community repository, these two keys need to be kept online and will be used to sign new metadata on every update.