From 18ce211ff4d04825975c21120842783fbf45bb3c Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Mon, 16 Dec 2013 09:48:58 -0500 Subject: [PATCH 1/5] Update README.md Line 13: Fix typo. Line 14: Add Bold text. Lines 94-96: Add remove_obsolete_targets() example. --- tuf/client/README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tuf/client/README.md b/tuf/client/README.md index 216a2a26..5072b2cf 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -10,8 +10,8 @@ information. The **tuf.libtuf** module can be used to create a TUF repository. -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. @@ -90,4 +90,8 @@ 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. +updater.remove_obsolete_targets(destination_directory) ``` From bf1c319f4af870365ce0cfdf516b355312bd5a64 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Mon, 16 Dec 2013 10:15:11 -0500 Subject: [PATCH 2/5] Update README.md Line 41: Add sub-heading. Lines 100-110: Add targets of role example. Lines 113-123: Add downloading specific target file example. --- tuf/client/README.md | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/tuf/client/README.md b/tuf/client/README.md index 5072b2cf..d8774b2b 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -2,11 +2,11 @@ **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/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. @@ -37,7 +37,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 @@ -95,3 +96,28 @@ for target in updated_targets: # tracked. updater.remove_obsolete_targets(destination_directory) ``` + +### Download Targets of a Role +```Python +# Example demonstrating an update that only downloads the targets of +# a specific role (i.e., 'targets/django'). + +updater.refresh() +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. + +updater.refresh() +target = updater.target('LICENSE.txt') +updated_target = updater.updated_targets([target], destination_directory) + +for target in updated_target: + updater.download_target(target, destination_directory) +``` From 026daacb7d45cdc0287c2bee029359d7078b088a Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Mon, 16 Dec 2013 10:48:03 -0500 Subject: [PATCH 3/5] Update README.md Line 18: Fix heading. Lines 76-78: Expand comment on refresh(). Lines 81-83: Expand comment on all_targets(). Lines 103: Fix heading. Lines 111-113: Add refresh_targets_metadata_chain() example. 115-116: Expand comment on refreshing target files and determining the ones that have changed. 128: Add refresh() comment. --- tuf/client/README.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/tuf/client/README.md b/tuf/client/README.md index d8774b2b..b541ad0c 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -15,7 +15,7 @@ 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. @@ -74,10 +74,13 @@ repository_mirrors = {'mirror1': {'url_prefix': 'http://localhost:8001', 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. +# 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. +# 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 @@ -97,12 +100,20 @@ for target in updated_targets: updater.remove_obsolete_targets(destination_directory) ``` -### Download Targets of a Role +### 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). +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) @@ -113,8 +124,10 @@ for target in updated_targets: ### Download Specific Target File ```Python # Example demonstrating an update that downloads a specific target. - -updater.refresh() + +# Refresh the metadata of the top-level roles (i.e., Root, Targets, Release, Timestamp). +updater.refresh() + target = updater.target('LICENSE.txt') updated_target = updater.updated_targets([target], destination_directory) From ac2192f22835adc947f88c8159ab122cddac730c Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Mon, 16 Dec 2013 11:59:42 -0500 Subject: [PATCH 4/5] Update README.md Lines: Add simple integration example and its output. Minor updates to comments. --- tuf/client/README.md | 48 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/tuf/client/README.md b/tuf/client/README.md index b541ad0c..0fb0dc9e 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -2,7 +2,7 @@ **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 +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 @@ -48,7 +48,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. @@ -73,12 +73,12 @@ 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 +# 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 of 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() @@ -96,7 +96,8 @@ for target in updated_targets: updater.download_target(target, destination_directory) # Remove any files from the destination directory that are no longer being -# tracked. +# 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) ``` @@ -128,9 +129,46 @@ for target in updated_targets: # 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 From 182368e9733b59fc9967f311cffc4bfab13e77a4 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Mon, 16 Dec 2013 13:39:54 -0500 Subject: [PATCH 5/5] Update README.md Minor updated to comments. --- tuf/client/README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/tuf/client/README.md b/tuf/client/README.md index 0fb0dc9e..9ef97fec 100644 --- a/tuf/client/README.md +++ b/tuf/client/README.md @@ -8,10 +8,11 @@ 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 also assist in integrating TUF with a -software updater. See **tuf.interposition.README** for more information on +software updater. See **tuf/interposition/README** for more information on interposing Python urllib calls with TUF. @@ -110,7 +111,8 @@ updater.remove_obsolete_targets(destination_directory) 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). +# 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, @@ -137,13 +139,13 @@ for target in updated_target: updater.download_target(target, destination_directory) ``` -###A Simple Integration Example with basic_client.py. +###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. +# 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]