theupdateframework / theupdateframework/specification

Spec should say when 'local' files are overwritten (5.1)

Open
#76 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
405
Forks
59
Avg merge
3d 4h
Merged PRs (30d)
1

Description

(I'm logging issues such as these mostly to help make the spec more precise. I hope it's useful.)

The update process described in Section 5.1 looks something like:

  1. Download timestamp, verify, and compare to old timestamp.
  2. If changed, download snapshot, verify, and compare to old snapshot.
  3. If root metadata changed, download new, verify, and start over.
  4. Download and verify other changed top-level metadata.

What does this not specify is when, say, the "old" timestamp that the client cached locally is replaced with the new timestamp from the server. This is somewhat subtle; it is not okay to replace the local copy of the timestamp with the server copy as soon as it has been verified and compared, because then we might do:

  1. Download timestamp, verify, compare to local. Notice changed, replace local copy.
  2. Download snapshot, verify, compare to local, notice root changed (perhaps just a new root key was added, nothing else), replace local copy.
  3. Download root, verify, start process over.
  4. Now we download the timestamp once again, verify it, and compare it to our local copy. Since we already replaced the local copy, we conclude it's not changed and we return "No changes" to the client.

This means we might fail to notice that there are other top-level metadata files that ought to have been replaced.

Incidentally, on a verification error in our implementation we actually delete the local timestamp and local snapshot after getting (and verifying) the new root info. We do this because, say, the timestamp key has been compromised and the attacker has set the file version to MAX_INT. Then if we don't do something to deal with this situation, clients would subsequently reject all further updates because the file version cannot change anymore. By removing the local files we basically reset the clients state to "we don't know what's on the server".

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Section 5.1 and trace the update sequence described in the issue, including the verification-error behavior. Clarify when locally cached timestamp and snapshot files are replaced, and ensure the reset behavior after verification errors is explicit; the section is done when these cases cannot cause missed metadata updates.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.