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. Updater should always be initialized with the bootstrap argument: pass bootstrap=None only to explicitly opt into using the cached root.json as the trust anchor.

  • refresh() can optionally be called to update and load all top-level metadata as described in the specification, using both locally cached metadata and metadata downloaded from the remote repository. If refresh is not done explicitly, it will happen automatically during the first target info lookup.

  • Updater can be used to download targets. For each target:

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

    • Updater.find_cached_target() can optionally be used to check if a target file is already locally cached.

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

Note that applications using Updater should be ‘single instance’ applications: running multiple instances that use the same cache directories at the same time is not supported.

A simple example of using the Updater to implement a Python TUF client that downloads target files is available in examples/client.

Notes on how Updater uses HTTP by default:

  • urllib3 is the HTTP library

  • Typically all requests are retried by urllib3 three times (in cases where this seems useful)

  • Operating system certificate store is used for TLS, in other words certifi is not used as the certificate source

  • Proxy use can be configured with https_proxy and other similar environment variables

All of the HTTP decisions can be changed with fetcher argument: Custom FetcherInterface implementations are possible. The alternative RequestsFetcher implementation is also provided (although deprecated).

class Updater(metadata_dir, metadata_base_url, target_dir=None, target_base_url=None, fetcher=None, config=None, *, bootstrap)

Creates a new Updater instance and loads trusted root metadata.

Parameters:

  • metadata_dir (str) – Local metadata directory. Directory must be writable. If bootstrap is None, this directory must contain a trusted root.json file.

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

  • target_dir (str | None) – Local targets directory. Directory must be writable. It will be used as the default target download directory by find_cached_target() and download_target()

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

  • fetcher (FetcherInterface | None) – Optional; FetcherInterface implementation used to download both metadata and targets. Default is Urllib3Fetcher

  • config (UpdaterConfig | None) – Optional; UpdaterConfig could be used to setup common configuration options.

  • bootstrap (bytes | None) – Initial root metadata bytes. This argument is required. Pass the embedded root metadata bytes for secure initialization. Pass None only if you explicitly want to use the cached root.json as the trust anchor (not recommended for most deployments).

Raises:

  • OSError – Local root.json cannot be read

  • RepositoryError – Local root.json is invalid

download_target(targetinfo, filepath=None, target_base_url=None)

Download the target file specified by targetinfo.

Parameters:

  • targetinfo (TargetFile) – TargetFile from get_targetinfo().

  • filepath (str | None) – Local path to download into. If None, the file is downloaded into directory defined by target_dir constructor argument using a generated filename. If file already exists, it is overwritten.

  • target_base_url (str | None) – Base URL used to form the final target download URL. Default is the value provided in Updater()

Raises:

  • ValueError – Invalid arguments

  • DownloadError – Download of the target file failed in some way

  • RepositoryError – Downloaded target failed to be verified in some way

  • OSError – Failed to write target to file

Returns:

Local path to downloaded file

Return type:

str

find_cached_target(targetinfo, filepath=None)

Check whether a local file is an up to date target.

Parameters:

  • targetinfo (TargetFile) – TargetFile from get_targetinfo().

  • filepath (str | None) – Local path to file. If None, a file path is generated based on target_dir constructor argument.

Raises:

ValueError – Incorrect arguments

Returns:

Local file path if the file is an up to date target file. None if file is not found or it is not up to date.

Return type:

str | None

get_targetinfo(target_path)

Return TargetFile instance with information for target_path.

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

If refresh() has not been called before calling get_targetinfo(), the refresh will be done implicitly.

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

Parameters:

target_path (str) – path-relative-URL string that uniquely identifies the target within the repository.

Raises:

  • OSError – New metadata could not be written to disk

  • RepositoryError – Metadata failed to verify in some way

  • DownloadError – Download of a metadata file failed in some way

Returns:

TargetFile instance or None.

Return type:

TargetFile | None

refresh()

Refresh 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.

A refresh() can be done only once during the lifetime of an Updater. If refresh() has not been explicitly called before the first get_targetinfo() call, it will be done implicitly at that time.

The metadata for delegated roles is not updated by refresh(): that happens on demand during get_targetinfo(). However, if the repository uses consistent_snapshot, then all metadata downloaded by the Updater will use the same consistent repository state.

Raises:

  • OSError – New metadata could not be written to disk

  • RepositoryError – Metadata failed to verify in some way

  • DownloadError – Download of a metadata file failed in some way

Return type:

None