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.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.
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
# where metadata and targets will be downloaded from.
updater = Updater(
metadata_dir="~/tufclient/metadata/",
metadata_base_url="http://localhost:8000/tuf-repo/",
target_dir="~/tufclient/downloads/",
target_base_url="http://localhost:8000/targets/",
)
# Update metadata, then download target if needed
info = updater.get_targetinfo("file.txt")
path = updater.find_cached_target(info)
if path is None:
path = updater.download_target(info)
print(f"Local file {path} contains target {info.path}")
- class Updater(metadata_dir, metadata_base_url, target_dir=None, target_base_url=None, fetcher=None, config=None)
Creates a new Updater instance and loads trusted root metadata.
- Parameters
metadata_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_dir (Optional[str]) – Local targets directory. Directory must be writable. It will be used as the default target download directory by
find_cached_target()
anddownload_target()
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, filepath=None, target_base_url=None)
Downloads the target file specified by
targetinfo
.- Parameters
targetinfo (TargetFile) – TargetFile from
get_targetinfo()
.filepath (Optional[str]) – 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 (Optional[str]) – 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
Local path to downloaded file
- Return type
str
- find_cached_target(targetinfo, filepath=None)
Checks whether a local file is an up to date target
- Parameters
targetinfo (TargetFile) – TargetFile from
get_targetinfo()
.filepath (Optional[str]) – Local path to file. If None, a file path is generated
argument. (based on target_dir constructor) –
- 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
Optional[str]
- get_targetinfo(target_path)
Returns TargetFile instance with information for ‘target_path’.
The return value can be used as an argument to
download_target()
andfind_cached_target()
.If
refresh()
has not been called before callingget_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) – A 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
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.
A
refresh()
can be done only once during the lifetime of an Updater. Ifrefresh()
has not been explicitly called before the firstget_targetinfo()
call, it will be done implicitly at that time.The metadata for delegated roles is not updated by
refresh()
: that happens on demand duringget_targetinfo()
. However, if the repository uses consistent_snapshot, then all metadata downloaded 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
TODO – download-related errors
- Return type
None