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 thebootstrap
argument: if this is not possible, it can be initialized from cache only.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 sourceProxy 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=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 (str | None) – 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 (str | None) –
Optional
; Default base URL for all remote target downloads. Can be individually set indownload_target()
fetcher (FetcherInterface | None) –
Optional
;FetcherInterface
implementation used to download both metadata and targets. Default isUrllib3Fetcher
config (UpdaterConfig | None) –
Optional
;UpdaterConfig
could be used to setup common configuration options.bootstrap (bytes | None) –
Optional
; initial root metadata. A bootstrap root should always be provided. If it is not, the current root.json in the metadata cache is used as the initial root.
- 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
fromget_targetinfo()
.filepath (str | None) – 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 (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
fromget_targetinfo()
.filepath (str | None) – 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:
str | None
- get_targetinfo(target_path)
Return
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:
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. 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 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