From dceb6bcc9bbdaf09b3f5fc52b2ac67065bbddb70 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 13:22:31 -0400 Subject: [PATCH 1/7] Rename the keys and metadata for role X and Y Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index 300e8827..d47e4b9b 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -75,7 +75,8 @@ Enter a password for the encrypted key (tufkeystore/root_key): (2) add keys to the top-level roles. (3) delegate trust of particular target files to another role X, where role X -has a signature threshold 2 and is marked as a terminating delegation. +has a signature threshold 2 and is marked as a terminating delegation. The +keys for role X and Y should be created prior to performing the delegation. (4) Delegate from role X to role Y. @@ -87,8 +88,8 @@ the expected file that should be downloaded by the client. (7) halt the server, add README.txt to the Targets role, restart server, and fetch the Target's role README.txt. -(8) Add LICENSE to 'yrole' and demonstate that the client must not fetch it -because xrole is a terminating delegation (and hasn't signed for it). +(8) Add LICENSE to 'role_y' and demonstate that the client must not fetch it +because 'role_x' is a terminating delegation (and hasn't signed for it). (1) and (2) ```Bash @@ -109,19 +110,19 @@ Enter a password for the encrypted key (tufkeystore/targets_key): (3) and (4) ```Bash -$ repo.py --delegate "README.*" "LICENSE" --delegatee xrole --pubkeys +$ repo.py --delegate "README.*" "LICENSE" --delegatee role_x --pubkeys tufkeystore/xkey.pub tufkeystore/xkey2.pub --threshold 2 --terminating -$ repo.py --sign tufkeystore/xkey tufkeystore/xkey2 --role xrole +$ repo.py --sign tufkeystore/xkey tufkeystore/xkey2 --role role_x $ repo.py --key ed25519 --filename ykey -$ repo.py --delegate "README.*" "LICENSE" --delegatee yrole --role xrole +$ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x --pubkeys tufkeystore/ykey.pub --sign tufkeystore/xkey tufkeystore/xkey2 -$ repo.py --sign tufkeystore/ykey --role yrole +$ repo.py --sign tufkeystore/ykey --role role_y ``` (5) and (6) ```Bash -$ echo "xrole's readme" > README.txt -$ repo.py --add README.txt --role xrole --sign tufkeystore/xkey tufkeystore/xkey2 +$ echo "role_x's readme" > README.txt +$ repo.py --add README.txt --role role_x --sign tufkeystore/key_x tufkeystore/key_x2 ``` Serve the repo @@ -130,11 +131,11 @@ $ cd tufrepo/ $ python -m SimpleHTTPServer 8001 ``` -Fetch the xrole's README.txt +Fetch the role x's README.txt ```Bash $ client.py --repo http://localhost:8001 README.txt $ cat tuftargets/README.txt -xrole's readme +role_x's readme ``` (7) @@ -157,8 +158,8 @@ Target role's readme (8) ```Bash -$ echo "yrole's license" > LICENSE -$ repo.py --add LICENSE --role yrole --sign tufkeystore/ykey +$ echo "role_y's license" > LICENSE +$ repo.py --add LICENSE --role role_y --sign tufkeystore/key_y ``` ```Bash From 58a00d6b8b5fd8cfaa0c536bf86720c2cc523e73 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 13:33:19 -0400 Subject: [PATCH 2/7] Add missing command to create key_x and key_x2 Add blank lines between commands to help readability Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index d47e4b9b..ed03c4b5 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -110,13 +110,19 @@ Enter a password for the encrypted key (tufkeystore/targets_key): (3) and (4) ```Bash +$ repo.py --key ed25519 --filename key_x +$ repo.py --key ed25519 --filename key_x2 + $ repo.py --delegate "README.*" "LICENSE" --delegatee role_x --pubkeys - tufkeystore/xkey.pub tufkeystore/xkey2.pub --threshold 2 --terminating -$ repo.py --sign tufkeystore/xkey tufkeystore/xkey2 --role role_x -$ repo.py --key ed25519 --filename ykey + tufkeystore/key_x.pub tufkeystore/key_x2.pub --threshold 2 --terminating +$ repo.py --sign tufkeystore/key_x tufkeystore/key_x2 --role role_x + +$ repo.py --key ed25519 --filename key_y + $ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x - --pubkeys tufkeystore/ykey.pub --sign tufkeystore/xkey tufkeystore/xkey2 -$ repo.py --sign tufkeystore/ykey --role role_y + --pubkeys tufkeystore/key_y.pub --sign tufkeystore/key_x tufkeystore/key_x2 + +$ repo.py --sign tufkeystore/key_y --role role_y ``` (5) and (6) From db7b9bd4034cfb647c1b74e204623943145e836a Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 13:47:23 -0400 Subject: [PATCH 3/7] Include steps being follows and revise text in 'Replace a top-level key' Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index ed03c4b5..c0e5b989 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -10,12 +10,17 @@ (4) fetch the trusted file from the delegated role. ```Bash +Step (1) $ repo.py --init + +Step (2) $ repo.py --key ed25519 --filename mykey $ repo.py --delegate "README.*" --delegatee myrole --pubkeys tufkeystore/mykey.pub $ repo.py --sign tufkeystore/mykey --role myrole Enter a password for the encrypted key (tufkeystore/mykey): $ echo "my readme text" > README.txt + +Step (3) $ repo.py --add README.txt --role myrole --sign tufkeystore/mykey Enter a password for the encrypted key (tufkeystore/mykey): ``` @@ -26,8 +31,8 @@ $ cd tufrepo/ $ python -m SimpleHTTPServer 8001 ``` -Fetch the repo's README.txt ```Bash +Step (4) $ client.py --repo http://localhost:8001 README.txt $ tree . . @@ -55,15 +60,17 @@ $ tree . ## Replace a top-level key ## -Note: The top-level keys should be named "root_key," "targets_key," "snapshot_key," -and "root_key." Additional top-level keys may be named anything, and must -be used with --sign. +The filename of the top-level keys must be "root_key," "targets_key," +"snapshot_key," and "root_key." The filename can vary for any additional +top-level key. ```Bash $ repo.py --init $ repo.py --distrust --pubkeys tufkeystore/root_key.pub --role root + $ repo.py --key ed25519 --filename root_key $ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root + $ repo.py --sign tufkeystore/root_key --role root Enter a password for the encrypted key (tufkeystore/root_key): ``` @@ -91,7 +98,7 @@ fetch the Target's role README.txt. (8) Add LICENSE to 'role_y' and demonstate that the client must not fetch it because 'role_x' is a terminating delegation (and hasn't signed for it). -(1) and (2) +Steps (1) and (2) ```Bash $ repo.py --init --consistent --bare $ repo.py --key ed25519 --filename root_key @@ -108,7 +115,7 @@ $ repo.py --sign tufkeystore/targets_key --role targets Enter a password for the encrypted key (tufkeystore/targets_key): ``` -(3) and (4) +Steps (3) and (4) ```Bash $ repo.py --key ed25519 --filename key_x $ repo.py --key ed25519 --filename key_x2 @@ -125,7 +132,7 @@ $ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x $ repo.py --sign tufkeystore/key_y --role role_y ``` -(5) and (6) +Steps (5) and (6) ```Bash $ echo "role_x's readme" > README.txt $ repo.py --add README.txt --role role_x --sign tufkeystore/key_x tufkeystore/key_x2 @@ -144,15 +151,15 @@ $ cat tuftargets/README.txt role_x's readme ``` -(7) +Step (7) ```Bash -halt server... +halt the server... $ echo "Target role's readme" > README.txt $ repo.py --add README.txt -restart server... +restart the server... ``` ```Bash @@ -162,7 +169,7 @@ $ cat tuftargets/README.txt Target role's readme ``` -(8) +Step (8) ```Bash $ echo "role_y's license" > LICENSE $ repo.py --add LICENSE --role role_y --sign tufkeystore/key_y From bccba83f962129a4514b1e387678b998a443a784 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 14:15:11 -0400 Subject: [PATCH 4/7] Add introductory text, rename headings, change title Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index c0e5b989..e15d0bce 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -1,6 +1,12 @@ -# CLI Examples # +# CLI Usage Examples # -## Basic example ## +This document contains a few examples of creating repositories with the CLI. +The sections below correspond with a different example. Each section begins +with an outline of the steps to be followed by the user. + +## A basic example ## + +Steps: (1) initialize a repo. (2) delegate trust of target files to another role. @@ -59,7 +65,7 @@ $ tree . ``` -## Replace a top-level key ## +## An example of replacing a top-level key ## The filename of the top-level keys must be "root_key," "targets_key," "snapshot_key," and "root_key." The filename can vary for any additional top-level key. @@ -77,6 +83,8 @@ Enter a password for the encrypted key (tufkeystore/root_key): ## A more complicated example ## + +Steps: (1) create a bare repo. (2) add keys to the top-level roles. From d3c085249557e8d194c0f2ec0d34a23fe564c440 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 14:30:16 -0400 Subject: [PATCH 5/7] Outline the steps for the second example Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index e15d0bce..b9a6653c 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -70,13 +70,24 @@ The filename of the top-level keys must be "root_key," "targets_key," "snapshot_key," and "root_key." The filename can vary for any additional top-level key. +Steps: +(1) initialize a repo containing default keys for the top-level roles. +(2) distrust the default key for the root role. +(3) create a new key and trust its use with the root role. +(4) sign the root metadata file. + ```Bash +Step (1) $ repo.py --init + +Step (2) $ repo.py --distrust --pubkeys tufkeystore/root_key.pub --role root +Step (3) $ repo.py --key ed25519 --filename root_key $ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root +Step (4) $ repo.py --sign tufkeystore/root_key --role root Enter a password for the encrypted key (tufkeystore/root_key): ``` From 3d88d8bde187794abb268c7750bff3e41596ed2b Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 14:31:00 -0400 Subject: [PATCH 6/7] Remove obsolete text in the 'Clean' section of CLI.md Signed-off-by: Vladimir Diaz --- docs/CLI.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/CLI.md b/docs/CLI.md index 29ffcca5..d0b361c4 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -227,8 +227,6 @@ $ repo.py --verbose <0-5> ## Clean ## -Remove the files created via `repo.py --init`. - Delete the repo in the current working directory, or the one specified with `--path`. Specifically, the `tufrepo`, `tufclient`, and `tufkeystore` directories are deleted. From 6bf8a95a71184343cdcaa7cc9d23b1e4dc39d6a6 Mon Sep 17 00:00:00 2001 From: Vladimir Diaz Date: Wed, 27 Jun 2018 14:48:31 -0400 Subject: [PATCH 7/7] Minor edits to relocate text and introduction Signed-off-by: Vladimir Diaz --- docs/CLI_EXAMPLES.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/CLI_EXAMPLES.md b/docs/CLI_EXAMPLES.md index b9a6653c..7c1cc01c 100644 --- a/docs/CLI_EXAMPLES.md +++ b/docs/CLI_EXAMPLES.md @@ -1,12 +1,13 @@ # CLI Usage Examples # This document contains a few examples of creating repositories with the CLI. -The sections below correspond with a different example. Each section begins -with an outline of the steps to be followed by the user. +The sections below correspond with a different example, and each begins with an +outline of the steps to be followed by the user. ## A basic example ## Steps: + (1) initialize a repo. (2) delegate trust of target files to another role. @@ -71,6 +72,7 @@ The filename of the top-level keys must be "root_key," "targets_key," top-level key. Steps: + (1) initialize a repo containing default keys for the top-level roles. (2) distrust the default key for the root role. (3) create a new key and trust its use with the root role. @@ -96,6 +98,7 @@ Enter a password for the encrypted key (tufkeystore/root_key): ## A more complicated example ## Steps: + (1) create a bare repo. (2) add keys to the top-level roles. @@ -117,8 +120,8 @@ fetch the Target's role README.txt. (8) Add LICENSE to 'role_y' and demonstate that the client must not fetch it because 'role_x' is a terminating delegation (and hasn't signed for it). -Steps (1) and (2) ```Bash +Steps (1) and (2) $ repo.py --init --consistent --bare $ repo.py --key ed25519 --filename root_key $ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root @@ -134,8 +137,8 @@ $ repo.py --sign tufkeystore/targets_key --role targets Enter a password for the encrypted key (tufkeystore/targets_key): ``` -Steps (3) and (4) ```Bash +Steps (3) and (4) $ repo.py --key ed25519 --filename key_x $ repo.py --key ed25519 --filename key_x2 @@ -151,8 +154,8 @@ $ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x $ repo.py --sign tufkeystore/key_y --role role_y ``` -Steps (5) and (6) ```Bash +Steps (5) and (6) $ echo "role_x's readme" > README.txt $ repo.py --add README.txt --role role_x --sign tufkeystore/key_x tufkeystore/key_x2 ``` @@ -170,9 +173,9 @@ $ cat tuftargets/README.txt role_x's readme ``` -Step (7) ```Bash +Step (7) halt the server... $ echo "Target role's readme" > README.txt @@ -188,8 +191,8 @@ $ cat tuftargets/README.txt Target role's readme ``` -Step (8) ```Bash +Step (8) $ echo "role_y's license" > LICENSE $ repo.py --add LICENSE --role role_y --sign tufkeystore/key_y ```