Skip to content

Commit 4f01a31

Browse files
authored
Merge pull request #849 from theupdateframework/clarify_role_of_cli
Reframe CLI, revise quickstart, and reorganize tutorials
2 parents e82ce35 + 67dd649 commit 4f01a31

File tree

5 files changed

+312
-235
lines changed

5 files changed

+312
-235
lines changed

docs/CLI.md

Lines changed: 216 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
# CLI #
1+
# Command-Line Interface #
22

3-
The CLI requires a few dependencies and C extensions that can be installed with
4-
`pip install securesystemslib[crypto,pynacl]`.
3+
The TUF command-line interface (CLI) requires a full
4+
[TUF installation](INSTALLATION.rst). Be sure to include the installation of
5+
extra dependencies and C extensions (
6+
```pip install securesystemslib[crypto,pynacl]```).
57

6-
[CLI_EXAMPLES.md](CLI_EXAMPLES.md) covers more complex examples.
8+
The use of the CLI is documented with examples below.
79

810
----
11+
# Basic Examples #
12+
913
## Create a repository ##
1014

1115
Create a TUF repository in the current working directory. A cryptographic key
@@ -235,3 +239,211 @@ $ repo.py --clean
235239
$ repo.py --clean --path </path/to/dirty/repo>
236240
```
237241
----
242+
243+
244+
245+
246+
247+
248+
249+
250+
# Further Examples #
251+
252+
## Basic Update Delivery ##
253+
254+
Steps:
255+
256+
(1) initialize a repo.
257+
258+
(2) delegate trust of target files to another role.
259+
260+
(3) add a trusted file to the delegated role.
261+
262+
(4) fetch the trusted file from the delegated role.
263+
264+
```Bash
265+
Step (1)
266+
$ repo.py --init
267+
268+
Step (2)
269+
$ repo.py --key ed25519 --filename mykey
270+
$ repo.py --delegate "README.*" --delegatee myrole --pubkeys tufkeystore/mykey.pub
271+
$ repo.py --sign tufkeystore/mykey --role myrole
272+
Enter a password for the encrypted key (tufkeystore/mykey):
273+
$ echo "my readme text" > README.txt
274+
275+
Step (3)
276+
$ repo.py --add README.txt --role myrole --sign tufkeystore/mykey
277+
Enter a password for the encrypted key (tufkeystore/mykey):
278+
```
279+
280+
Serve the repo
281+
```Bash
282+
$ cd tufrepo/
283+
$ python -m SimpleHTTPServer 8001
284+
```
285+
286+
```Bash
287+
Step (4)
288+
$ client.py --repo http://localhost:8001 README.txt
289+
$ tree .
290+
.
291+
├── tuf.log
292+
├── tufrepo
293+
│   └── metadata
294+
│   ├── current
295+
│   │   ├── 1.root.json
296+
│   │   ├── myrole.json
297+
│   │   ├── root.json
298+
│   │   ├── snapshot.json
299+
│   │   ├── targets.json
300+
│   │   └── timestamp.json
301+
│   └── previous
302+
│   ├── 1.root.json
303+
│   ├── root.json
304+
│   ├── snapshot.json
305+
│   ├── targets.json
306+
│   └── timestamp.json
307+
└── tuftargets
308+
└── README.txt
309+
310+
5 directories, 13 files
311+
```
312+
313+
314+
## Correcting a Key ##
315+
The filename of the top-level keys must be "root_key," "targets_key,"
316+
"snapshot_key," and "root_key." The filename can vary for any additional
317+
top-level key.
318+
319+
Steps:
320+
321+
(1) initialize a repo containing default keys for the top-level roles.
322+
(2) distrust the default key for the root role.
323+
(3) create a new key and trust its use with the root role.
324+
(4) sign the root metadata file.
325+
326+
```Bash
327+
Step (1)
328+
$ repo.py --init
329+
330+
Step (2)
331+
$ repo.py --distrust --pubkeys tufkeystore/root_key.pub --role root
332+
333+
Step (3)
334+
$ repo.py --key ed25519 --filename root_key
335+
$ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root
336+
337+
Step (4)
338+
$ repo.py --sign tufkeystore/root_key --role root
339+
Enter a password for the encrypted key (tufkeystore/root_key):
340+
```
341+
342+
343+
## More Update Delivery ##
344+
345+
Steps:
346+
347+
(1) create a bare repo.
348+
349+
(2) add keys to the top-level roles.
350+
351+
(3) delegate trust of particular target files to another role X, where role X
352+
has a signature threshold 2 and is marked as a terminating delegation. The
353+
keys for role X and Y should be created prior to performing the delegation.
354+
355+
(4) Delegate from role X to role Y.
356+
357+
(5) have role X sign for a file also signed by the Targets role, to demonstrate
358+
the expected file that should be downloaded by the client.
359+
360+
(6) perform an update.
361+
362+
(7) halt the server, add README.txt to the Targets role, restart the server,
363+
and fetch the Target's role README.txt.
364+
365+
(8) Add LICENSE to 'role_y' and demonstrate that the client must not fetch it
366+
because 'role_x' is a terminating delegation (and hasn't signed for it).
367+
368+
```Bash
369+
Steps (1) and (2)
370+
$ repo.py --init --consistent --bare
371+
$ repo.py --key ed25519 --filename root_key
372+
$ repo.py --trust --pubkeys tufkeystore/root_key.pub --role root
373+
$ repo.py --key ecdsa --filename targets_key
374+
$ repo.py --trust --pubkeys tufkeystore/targets_key.pub --role targets
375+
$ repo.py --key rsa --filename snapshot_key
376+
$ repo.py --trust --pubkeys tufkeystore/snapshot_key.pub --role snapshot
377+
$ repo.py --key ecdsa --filename timestamp_key
378+
$ repo.py --trust --pubkeys tufkeystore/timestamp_key.pub --role timestamp
379+
$ repo.py --sign tufkeystore/root_key --role root
380+
Enter a password for the encrypted key (tufkeystore/root_key):
381+
$ repo.py --sign tufkeystore/targets_key --role targets
382+
Enter a password for the encrypted key (tufkeystore/targets_key):
383+
```
384+
385+
```Bash
386+
Steps (3) and (4)
387+
$ repo.py --key ed25519 --filename key_x
388+
$ repo.py --key ed25519 --filename key_x2
389+
390+
$ repo.py --delegate "README.*" "LICENSE" --delegatee role_x --pubkeys
391+
tufkeystore/key_x.pub tufkeystore/key_x2.pub --threshold 2 --terminating
392+
$ repo.py --sign tufkeystore/key_x tufkeystore/key_x2 --role role_x
393+
394+
$ repo.py --key ed25519 --filename key_y
395+
396+
$ repo.py --delegate "README.*" "LICENSE" --delegatee role_y --role role_x
397+
--pubkeys tufkeystore/key_y.pub --sign tufkeystore/key_x tufkeystore/key_x2
398+
399+
$ repo.py --sign tufkeystore/key_y --role role_y
400+
```
401+
402+
```Bash
403+
Steps (5) and (6)
404+
$ echo "role_x's readme" > README.txt
405+
$ repo.py --add README.txt --role role_x --sign tufkeystore/key_x tufkeystore/key_x2
406+
```
407+
408+
Serve the repo
409+
```Bash
410+
$ cd tufrepo/
411+
$ python -m SimpleHTTPServer 8001
412+
```
413+
414+
Fetch the role x's README.txt
415+
```Bash
416+
$ client.py --repo http://localhost:8001 README.txt
417+
$ cat tuftargets/README.txt
418+
role_x's readme
419+
```
420+
421+
422+
```Bash
423+
Step (7)
424+
halt the server...
425+
426+
$ echo "Target role's readme" > README.txt
427+
$ repo.py --add README.txt
428+
429+
restart the server...
430+
```
431+
432+
```Bash
433+
$ rm -rf tuftargets/ tuf.log
434+
$ client.py --repo http://localhost:8001 README.txt
435+
$ cat tuftargets/README.txt
436+
Target role's readme
437+
```
438+
439+
```Bash
440+
Step (8)
441+
$ echo "role_y's license" > LICENSE
442+
$ repo.py --add LICENSE --role role_y --sign tufkeystore/key_y
443+
```
444+
445+
```Bash
446+
$ rm -rf tuftargets/ tuf.log
447+
$ client.py --repo http://localhost:8001 LICENSE
448+
Error: 'LICENSE' not found.
449+
```

0 commit comments

Comments
 (0)