Elgato_dark/python-tuf
1
0
Fork 0
mirror of https://github.com/theupdateframework/python-tuf synced 2026-05-24 10:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'repository-tools' of https://github.com/theupdateframework/tuf into repository-tools

Browse source
This commit is contained in:
Vladimir Diaz 2013-12-16 13:40:13 -05:00
commit 8199033207
1 changed files with 97 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
tuf/client/README.md
View file

@ -2,20 +2,21 @@
**updater.py** is intended to be the only TUF module that software update
systems need to utilize for a low-level integration. It provides a single
class representing an updater that includes methods to download, install, and
verify metadata/target files in a secure manner. Importing **updater.py** and
instantiating its main class is all that is required by the client prior
to a TUF update request. The importation and instantiation steps allow
TUF to load all of the required metadata files and set the repository mirror
information.
verify metadata or target files in a secure manner. Importing
**tuf.client.updater.py** and instantiating its main class is all that is
required by the client prior to a TUF update request. The importation and
instantiation steps allow TUF to load all of the required metadata files
and set the repository mirror information.
The **tuf.libtuf** module can be used to create a TUF repository.
The **tuf.libtuf** module can be used to create a TUF repository. See
**tuf/README** for more information on creating TUF repositories.
The **tuf.interposition** package can can assist in integrating TUF with a
software updater. See 'tuf.interposition.README.md' for more information on
The **tuf.interposition** package can also assist in integrating TUF with a
software updater. See **tuf/interposition/README** for more information on
interposing Python urllib calls with TUF.
## Overview of the update process:
## Overview of the Update Process
1. The software update system instructs TUF to check for updates.
2. TUF downloads and verifies timestamp.txt.
@ -37,7 +38,8 @@ file.
the software update system.
## Example Client
## Example Client
### Refresh TUF Metadata and Download Target Files
```Python
# The client first imports the 'updater.py' module, the only module the
# client is required to import. The client will utilize a single class
@ -47,7 +49,7 @@ import tuf.client.updater
# The only other module the client interacts with is 'tuf.conf'. The
# client accesses this module solely to set the repository directory.
# This directory will hold the files downloaded from a remote repository.
tuf.conf.repository_directory = 'local-repository'
tuf.conf.repository_directory = 'path/to/local_repository'
# Next, the client creates a dictionary object containing the repository
# mirrors. The client may download content from any one of these mirrors.
@ -72,11 +74,14 @@ repository_mirrors = {'mirror1': {'url_prefix': 'http://localhost:8001',
# above.
updater = tuf.client.updater.Updater('updater', repository_mirrors)
# The client next calls the refresh() method to ensure it has the latest
# copies of the metadata files.
# The client calls the refresh() method to ensure it has the latest
# copies of the top-level metadata files (i.e., Root, Targets, Release,
# Timestamp).
updater.refresh()
# The target file information for all the repository targets is determined.
# The target file information of all the repository targets is determined next.
# Since all_targets() downloads the target files of every role, all role
# metadata is updated.
targets = updater.all_targets()
# Among these targets, determine the ones that have changed since the client's
@ -90,4 +95,82 @@ updated_targets = updater.updated_targets(targets, destination_directory)
# The updated target files are saved locally to 'destination_directory'.
for target in updated_targets:
updater.download_target(target, destination_directory)
# Remove any files from the destination directory that are no longer being
# tracked. For example, a target file from a previous release that has since
# been removed on the remote repository.
updater.remove_obsolete_targets(destination_directory)
```
### Download Target Files of a Role
```Python
# Example demonstrating an update that only downloads the targets of
# a specific role (i.e., 'targets/django').
# Refresh the metadata of the top-level roles (i.e., Root, Targets, Release, Timestamp).
updater.refresh()
# Refresh the minimum metadata needed to download the target files of a specified
# role (e.g., R1->R4->django, where R2 and R3 are excluded). The metadata for 'django'
# is also excluded, and expected to be updated by targets_of_role().
updater.refresh_targets_metadata_chain('targets/django')
# Update the file information of all the target files of the 'targets/django' role,
# and determine which target files have changed.
targets_of_django = updater.targets_of_role('targets/django')
updated_targets = updater.updated_targets(targets_of_django, destination_directory)
for target in updated_targets:
updater.download_target(target, destination_directory)
```
### Download Specific Target File
```Python
# Example demonstrating an update that downloads a specific target.
# Refresh the metadata of the top-level roles (i.e., Root, Targets, Release, Timestamp).
updater.refresh()
# target() updates role metadata when required.
target = updater.target('LICENSE.txt')
updated_target = updater.updated_targets([target], destination_directory)
for target in updated_target:
updater.download_target(target, destination_directory)
```
###A Simple Integration Example with basic_client.py
```Bash
# Assume a simple TUF repository has been setup with 'tuf.libtuf.py'.
$ basic_client.py --repo http://localhost:8001
# Metadata and target files are silently updated. An exception is only raised if an error,
# or attack, is detected. Inspect 'tuf.log' for the outcome of the update process.
$ cat tuf.log
[2013-12-16 16:17:05,267 UTC] [tuf.download] [INFO][_download_file:726@download.py]
Downloading: http://localhost:8001/metadata/timestamp.txt
[2013-12-16 16:17:05,269 UTC] [tuf.download] [WARNING][_check_content_length:589@download.py]
reported_length (545) < required_length (2048)
[2013-12-16 16:17:05,269 UTC] [tuf.download] [WARNING][_check_downloaded_length:656@download.py]
Downloaded 545 bytes, but expected 2048 bytes. There is a difference of 1503 bytes!
[2013-12-16 16:17:05,611 UTC] [tuf.download] [INFO][_download_file:726@download.py]
Downloading: http://localhost:8001/metadata/release.txt
[2013-12-16 16:17:05,612 UTC] [tuf.client.updater] [INFO][_check_hashes:636@updater.py]
The file\'s sha256 hash is correct: 782675fadd650eeb2926d33c401b5896caacf4fd6766498baf2bce2f3b739db4
[2013-12-16 16:17:05,951 UTC] [tuf.download] [INFO][_download_file:726@download.py]
Downloading: http://localhost:8001/metadata/targets.txt
[2013-12-16 16:17:05,952 UTC] [tuf.client.updater] [INFO][_check_hashes:636@updater.py]
The file\'s sha256 hash is correct: a5019c28a1595c43a14cad2b6252c4d1db472dd6412a9204181ad6d61b1dd69a
[2013-12-16 16:17:06,299 UTC] [tuf.download] [INFO][_download_file:726@download.py]
Downloading: http://localhost:8001/targets/file1.txt
[2013-12-16 16:17:06,303 UTC] [tuf.client.updater] [INFO][_check_hashes:636@updater.py]
The file's sha256 hash is correct: ecdc5536f73bdae8816f0ea40726ef5e9b810d914493075903bb90623d97b1d8