Updater

Client update workflow implementation

The Updater class provides an implementation of the TUF client workflow. Updater provides an API to query available targets and to download them in a secure manner: All downloaded files are verified by signed metadata.

High-level description of Updater functionality:

  • Initializing an Updater loads and validates the trusted local root metadata: This root metadata is used as the source of trust for all other metadata.

  • Calling refresh() will update root metadata and load all other top-level metadata as described in the specification, using both locally cached metadata and metadata downloaded from the remote repository.

  • When metadata is up-to-date, targets can be dowloaded. The repository snapshot is consistent so multiple targets can be downloaded without fear of repository content changing. For each target:

    • get_one_valid_targetinfo() is used to find information about a specific target. This will load new targets metadata as needed (from local cache or remote repository).

    • updated_targets() can be used to check if target files are already locally cached.

    • download_target() downloads a target file and ensures it is verified correct by the metadata.

Below is a simple example of using the Updater to download and verify “file.txt” from a remote repository. The required environment for this example is:

  • A webserver running on http://localhost:8000, serving TUF repository metadata at “/tuf-repo/” and targets at “/targets/”

  • Local metadata directory “~/tufclient/metadata/” is writable and contains a root metadata version for the remote repository

  • Download directory “~/tufclient/downloads/” is writable

Example:

from tuf.ngclient import Updater

# Load trusted local root metadata from client metadata cache. Define the
# remote repository metadata URL prefix and target URL prefix.
updater = Updater(
    repository_dir="~/tufclient/metadata/",
    metadata_base_url="http://localhost:8000/tuf-repo/",
    target_base_url="http://localhost:8000/targets/",
)

# Update top-level metadata from remote
updater.refresh()

# Securely download a target:
# Update target metadata, then download and verify target
targetinfo = updater.get_one_valid_targetinfo("file.txt")
updater.download_target(targetinfo, "~/tufclient/downloads/")
class Updater(repository_dir, metadata_base_url, target_base_url=None, fetcher=None, config=None)

Creates a new Updater instance and loads trusted root metadata.

Parameters

  • repository_dir (str) – Local metadata directory. Directory must be writable and it must contain a trusted root.json file.

  • metadata_base_url (str) – Base URL for all remote metadata downloads

  • target_base_url (Optional[str]) – Optional; Default base URL for all remote target downloads. Can be individually set in download_target()

  • fetcher (Optional[FetcherInterface]) – Optional; FetcherInterface implementation used to download both metadata and targets. Default is RequestsFetcher

  • config (Optional[UpdaterConfig]) –

Raises

  • OSError – Local root.json cannot be read

  • RepositoryError – Local root.json is invalid

download_target(targetinfo, destination_directory, target_base_url=None)

Downloads the target file specified by ‘targetinfo’.

Parameters

  • targetinfo (TargetFile) – TargetFile instance received from get_one_valid_targetinfo() or updated_targets().

  • destination_directory (str) – existing local directory to download into. Note that new directories may be created inside destination_directory as required.

  • target_base_url (Optional[str]) – Optional; Base URL used to form the final target download URL. Default is the value provided in Updater()

Raises

  • ValueError – Invalid arguments

  • TODO – download-related errors

  • TODO – file write errors

Returns

Path to downloaded file

Return type

str

get_one_valid_targetinfo(target_path)

Returns TargetFile instance with information for ‘target_path’.

The return value can be used as an argument to download_target() and updated_targets().

refresh() must be called before calling get_one_valid_targetinfo(). Subsequent calls to get_one_valid_targetinfo() will use the same consistent repository state: Changes that happen in the repository between calling refresh() and get_one_valid_targetinfo() will not be seen by the updater.

As a side-effect this method downloads all the additional (delegated targets) metadata it needs to return the target information.

Parameters

target_path (str) – A target identifier that is a path-relative-URL string (https://url.spec.whatwg.org/#path-relative-url-string). Typically this is also the unix file path of the eventually downloaded file.

Raises

  • OSError – New metadata could not be written to disk

  • RepositoryError – Metadata failed to verify in some way

  • TODO – download-related errors

Returns

A TargetFile instance or None.

Return type

Optional[TargetFile]

refresh()

Refreshes top-level metadata.

Downloads, verifies, and loads metadata for the top-level roles in the specified order (root -> timestamp -> snapshot -> targets) implementing all the checks required in the TUF client workflow.

The metadata for delegated roles are not refreshed by this method as that happens on demand during get_one_valid_targetinfo().

The refresh() method should be called by the client before any other method calls.

Raises

  • OSError – New metadata could not be written to disk

  • RepositoryError – Metadata failed to verify in some way

  • TODO – download-related errors

Return type

None

static updated_targets(targets, destination_directory)

Checks whether local cached target files are up to date

After retrieving the target information for the targets that should be updated, updated_targets() can be called to determine which targets have changed compared to locally stored versions.

All the targets that are not up-to-date in destination_directory are returned in a list. The list items can be downloaded with ‘download_target()’.

Parameters

  • targets (List[TargetFile]) –

  • destination_directory (str) –

Return type

List[TargetFile]