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.
A simple example of using the Updater to implement a Python TUF client that downloads target files is available in examples/client_example.
- 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 indownload_target()
fetcher (Optional[FetcherInterface]) –
Optional
;FetcherInterface
implementation used to download both metadata and targets. Default isRequestsFetcher
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
fromget_targetinfo()
.filepath (Optional[str]) – Local path to download into. If
None
, the file is downloaded into directory defined bytarget_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
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)
Checks whether a local file is an up to date target
- Parameters
targetinfo (TargetFile) –
TargetFile
fromget_targetinfo()
.filepath (Optional[str]) – Local path to file. If
None
, a file path is generated based ontarget_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
Optional[str]
- get_targetinfo(target_path)
Returns
TargetFile
instance with information fortarget_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) – 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 orNone
.- 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
DownloadError – Download of a metadata file failed in some way
- Return type
None