Skip to content

Update updater workflow doc in client/updater.py #1172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Update updater workflow doc in client/updater.py #1172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
710c9bf
Update updater workflow doc in client/updater.py
MVrachev Oct 9, 2020
138be5d
Update doc about client updater workflow
MVrachev Feb 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions tuf/client/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,29 @@ The **tuf.repository_tool** module can be used to create a TUF repository. See

## Overview of the Update Process

1. The software update system instructs TUF to check for updates.
0. The software update system instructs TUF to check for updates.

2. TUF downloads and verifies timestamp.json.
1. Tuf loads the trusted root metadata file.s
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Tuf loads the trusted root metadata file.s
1. TUF loads the trusted root metadata file.


3. If timestamp.json indicates that snapshot.json has changed, TUF downloads and
verifies snapshot.json.
2. Updates the root metadata file to the latest trustworthy version.
Establish a trusted line of continuity to the latest root version.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you put those two sentences somehow into relation to each other?


4. TUF determines which metadata files listed in snapshot.json differ from those
described in the last snapshot.json that TUF has seen. If root.json has changed,
the update process starts over using the new root.json.
3. Download and validates the timestamp metadata file.

5. TUF provides the software update system with a list of available files
according to targets.json.
4. If timestamp.json indicates that snapshot.json has changed, TUF downloads
and verifies snapshot.json.

6. The software update system instructs TUF to download a specific target
file.
5. If snapshot.json indicates that any of the top-level targets metadata and/or
delegated targets metadata has changed, TUF downloads and verifies targets.json
and/or all changed delegated target files.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that there is a difference between target (w/o s) and targets (with s) files. It's easy to mix them up, that's why I usually say "targets metadata files" to better distinguish from non-metadata target files.

Suggested change
and/or all changed delegated target files.
and/or all changed delegated targets metadata files.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, is this even accurate? Shouldn't the client, according to the spec, only download delegated targets metadata that is relevant for the desired target file, instead of all changed?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I think we should mention the traversal of the delegation graph here in order to resolve the correct targets metadata for a target file.


7. TUF downloads and verifies the file and then makes the file available to
the software update system.
6. Verify the desired target against its target's metadata.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does it verify the target before downloading it?


7. The software update system instructs TUF to download a specific target
file.

8. TUF downloads and verifies the file and then makes the file available to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "verifies the file" mean here?

the software update system.


If at any point in the above procedure there is a problem (i.e., if unexpired,
Expand Down
26 changes: 15 additions & 11 deletions tuf/client/updater.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,24 +29,28 @@

An overview of the update process:

1. The software update system instructs TUF to check for updates.
0. The software update system instructs TUF to check for updates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All comments in README.md above apply to tuf/client/updater.py as well. Maybe we should de-duplicate? E.g. just point to the README.md here? What do others think?


2. TUF downloads and verifies timestamp.json.
1. Tuf loads the trusted root metadata file.s

3. If timestamp.json indicates that snapshot.json has changed, TUF downloads
and verifies snapshot.json.
2. Updates the root metadata file to the latest trustworthy version.
Establish a trusted line of continuity to the latest root version.

4. TUF determines which metadata files listed in snapshot.json differ from
those described in the last snapshot.json that TUF has seen. If root.json
has changed, the update process starts over using the new root.json.
3. Download and validates the timestamp metadata file.

5. TUF provides the software update system with a list of available files
according to targets.json.
4. If timestamp.json indicates that snapshot.json has changed, TUF downloads
and verifies snapshot.json.

6. The software update system instructs TUF to download a specific target
5. If snapshot.json indicates that any of the top-level targets metadata and/or
delegated targets metadata has changed, TUF downloads and verifies targets.json
and/or all changed delegated target files.

6. Verify the desired target against its target's metadata.

7. The software update system instructs TUF to download a specific target
file.

7. TUF downloads and verifies the file and then makes the file available to
8. TUF downloads and verifies the file and then makes the file available to
the software update system.

<Example Client>
Expand Down