Updater
The purpose of the updater is to securely pull the authentication repository and the specified target repositories. This means that we want to validate all of the repositories before pulling the changes. The main idea is to rely on TUF's updater as much as possible, redefining only parts of the code which download files and check expiration time of metadata. This means that all security checks provided by the TUF updater will be executed. This document is meant to go into some technical details, see TUF specification for an overview of the update process.
There are a few differences between what TAF's updater needs achieve and what the TUF's updater was designed to do:
-
TUF's updater downloads files from the specified URL, whereas downloading in our case means showing a file at a specific revision.
-
TUF's updater assumes that a client wants to securely download the newest files from the specified mirrors, regardless of what the version of these files they currently have. On the other hand, we want to check validity of all commits pushed after the last time the client pulled the changes. We do not want to simply check if the last commit is valid.
- When validating an older commit, it can be expected that some of the metadata files will be expired. We do not want the update to fail because of that. TUF's updater raises an error if an expired metadata file is downloaded. We want to make sure that the metadata files was not expired when it was committed.
- In order to validate that a commit is valid, we want to ensure that metadata files which should remain the same according to their referent, did remain the same. For instance, if snapshot indicates that targets remained the same, we want to check if that is the case. If TUF's updater determines that the client has the latest version of a metadata file, it will only log that message and proceed to check the next metadata file.
- Once the authentication repository is validated and securely pulled, we want to securely update the target repositories. This task is completely unrelated to TUF's updater.
For the above listed reasons, we cannot simply use TUF's updater like described in its tutorial. Some of the differences can be overcome by performing the update multiple times (once per commit). However, not all can be accomplished without slightly modifying the TUF's updater, at least for now, which is why TAF requires our fork of the TUF project. The following represents the main ideas of the TAF updater:
-
We want to modify TUF's updater as little as possible. The TUF team is planning to refactor and enhance their updater and we want to be able to update our fork easily. Furthermore, if changes made to the TUF updater enable us to implement our updater without having to fork TUF, we want to be able to do so without too many problems. In order to make as little modifications as possible, so we make sure to set everything up as per TUF updater's requirements:
-
TUF updater expects to receive a map of mirrors
repository_mirrors
, where for each mirror its url, metadata path, target path and confined target directories are defined. We'll use this parameter to defined the authentication repository's url and relative paths of targets and metadata directories, ignoring the optional confined target directories list. -
TUF's updater expects existence of two directories:
current
andprevious
, located inside the client's directory metadata (repository which is being updated). These directories should contain the current and previous metadata files. Before refreshing the metadata files using the TUF updater, these two directories must exist and must contain the client's current metadata files. The client must at least haveroot.json
before updating the metadata using TUF's updater. So, we copy the metadata as they were at the last commit the client pulled to these directories. If the client has not pulled the authentication repository yet, the initial metadata files (at the initial revision) are the two directories. After a successful update of a metadata file, it is copied tocurrent
. These two directories are deleted after the validation is done, successfully or unsuccessfully. -
We view commits as mirrors from which metadata and target files are downloaded.
-
We provided a way of customizing the TUF updater using a so-called handler classes. These classes contain methods for acquiring metadata and target files. TUF updater receives the handler class as an input parameter. This enables us to load metadata and targets from the git repository, at a specified revision. As mentioned earlier, we also need to redefine how it is checked if a metadata file is expired or not, so this was also moved to the handler class. These changes do not ruin TUF updater original functionality. All of the original tests still pass.
-
New metadata files (not counting delegated roles) are acquired by calling TUF's
refresh
. Metadata files belonging to the delegated roles are updated byget_current_targets
. Information about a target file is obtained usingget_one_valid_targetinfo
-
Since TUF does not provide a way to gradually update metadata and target files (except for
root.json
), that has to be handled by TUF. So, TAF's updater calls TUF's updater multiple times. Our handler,GitUpdateHandler
finds all commits that were pushed after the last time the client pulled the changes. The basic idea is to traverse trough these commits and update metadata files and targets for each of them, thus validating all revisions.