From 907186e6a47d0560d0bdbdce54fcf8e32df55f4b Mon Sep 17 00:00:00 2001 From: Sebastien Awwad Date: Thu, 4 Apr 2019 17:14:13 -0400 Subject: [PATCH] DOC: revise quickstart and reorganize tutorials: - correctly frame the CLI's current state as a tutorial toy. - provide a friendlier quickstart that puts what it's doing into perspective and guides you to next steps. - provide a better sense of what each tutorial/quickstart doc is for. - make the getting started page slightly more friendly. Signed-off-by: Sebastien Awwad --- docs/GETTING_STARTED.rst | 9 ++-- docs/QUICKSTART.md | 104 +++++++++++++++++++++++++++++++-------- 2 files changed, 88 insertions(+), 25 deletions(-) diff --git a/docs/GETTING_STARTED.rst b/docs/GETTING_STARTED.rst index 29552808ee..fc775ea7c3 100644 --- a/docs/GETTING_STARTED.rst +++ b/docs/GETTING_STARTED.rst @@ -1,9 +1,8 @@ Getting Started --------------- +- `Overview of TUF `_ - `Installation `_ -- `Contributors `_ -- `Quickstart `_ -- `CLI `_ -- `CLI Usage Examples `_ -- `Tutorial `_ +- Beginner Tutorials (using the basic command-line interface): `Quickstart `_; `CLI Tutorial `_; `CLI Further Examples `_ +- `Advanced Tutorial `_ +- `Guidelines for Contributors `_ diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index c6ea4ed24f..322ca7fe93 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,21 +1,44 @@ # Quickstart # -The CLI requires a few dependencies and C extensions that can be installed with -`pip install securesystemslib[crypto,pynacl]`. +In this quickstart tutorial, we'll use the basic TUF command-line interface +(CLI), which includes the `repo.py` script and the `client.py` script, to set +up a repository with an update and metadata about that update, then download +and verify that update as a client. + +Unlike the underlying TUF modules that the CLI uses, the CLI itself is a bit +bare-bones. Using the CLI is the easiest way to familiarize yourself with +how TUF works, however. It will serve as a very basic update system and use ---- -The following is a basic workflow in four steps: -**Step (1)** - Initialize a repo. The `tufrepo`, `tufkeystore`, and -`tufclient` directories are created in the current working directory. +**Step (0)** - Make sure TUF is installed + +See the [installation instructions for TUF](docs/INSTALLATION.rst). +The TUF CLI makes use of some crypto dependencies, so please include the +optional `pip install securesystemslib[crypto,pynacl]` step. + + +**Step (1)** - Create a basic repository and client + +The following command will set up a basic update repository and basic client +that knows about the repository. `tufrepo`, `tufkeystore`, and +`tufclient` directories will be created in the current directory. + ```Bash $ repo.py --init ``` -Four sets of keys are created in the `tufkeystore` directory and metadata -is initiated in the `tufrepo` and `tufclient` directories. -**Step (2)** - Add a target file to the repo. The file size and hashes of -the target file are also written to the Targets metadata file. +Four sets of keys are created in the `tufkeystore` directory. Initial metadata +about the repository is created in the `tufrepo` directory, and also provided +to the client in the `tufclient` directory. + + +**Step (2)** - Add an update to the repository. + +We'll create a target file that will later be delivered as an update to clients. +Metadata about that file will be created and signed, and added to the +repository's metadata. + ```Bash $ echo 'Test file' > testfile $ repo.py --add testfile @@ -38,21 +61,38 @@ tufrepo/ 3 directories, 11 files ``` -The new file `testfile` is added and metadata is updated in the `tufrepo` directory. + +The new file `testfile` is added to the repository, and metadata is updated in +the `tufrepo` directory. The Targets metadata (`targets.json`) now includes +the file size and hashes of the `testfile` target file, and this metadata is +signed by the Targets role's key, so that clients can verify that metadata +about `testfile` and then verify `testfile` itself. + **Step (3)** - Serve the repo + +We'll host a toy http server containing the `testfile` update and the +repository's metadata. + ```Bash $ cd "tufrepo/" +$ python3 -m http.server 8001 + +# or, if you are using Python2: $ python -m SimpleHTTPServer 8001 -or with Python 3... -$ python3 -m http.server 8001 ``` -**Step (4)** - Fetch a target file from the repo. The client downloads -any required metadata and the requested target file. +**Step (4)** - Obtain and verify the `testfile` update on a client. + +The client can request the package `testfile` from the repository. TUF will +download and verify metadata from the repository as necessary to determine +what the trustworthy hashes and length of `testfile` are, then download +the target `testfile` from the repository and keep it only if it matches that +trustworthy metadata. + ```Bash -$ cd "tufclient/" +$ cd "../tufclient/" $ client.py --repo http://localhost:8001 testfile $ tree . @@ -75,11 +115,35 @@ $ tree 5 directories, 11 files ``` -client.py verified metadata from the server and downloaded content. The client has now verified and obtained `testfile`. -The scope of TUF ends here. + +Now that a trustworthy update target has been obtained, an updater can proceed +however it normally would to install or use the update. ---- -See [CLI.md](CLI.md) and [CLI_EXAMPLES.md](CLI_EXAMPLES.md) to learn about the -other supported CLI options. A [tutorial](TUTORIAL.md) is also available, and -intended for users that want more control over the repo creation process. +### Next Steps + +TUF provides functionality for both ends of a software update system, the +**update provider** and the **update client**. + +`repo.py` made use of `tuf.repository_tool`'s functionality for an update +provider, helping you produce and sign metadata about your updates. + +`client.py` made use of `tuf.client.updater`'s client-side functionality, +performing download and the critical verification steps for metadata and the +update itself. + +You can look at [CLI.md](CLI.md) and [CLI_EXAMPLES.md](CLI_EXAMPLES.md) to toy +with the TUF CLI a bit more. After that, try out using the underlying modules +for a great deal more control. The more detailed [TUF Tutorial](TUTORIAL.md) +shows you how to use them. + +Ultimately, a sophisticated update client will use or re-implement those +underlying modules. The TUF design is intended to play well with any update +workflow. + +Please provide feedback or questions for this or other tutorials, or +TUF in general, by checking out +[our contact info](https://github.com/theupdateframework/tuf#contact), or +creating [issues](https://github.com/theupdateframework/tuf/issues) in this +repository!