diff --git a/tuf/client/README.md b/tuf/client/README.md index 216a2a26..9ef97fec 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -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