Client workflow lacks detail

[jawi]

I'm trying to get my head around the update workflow from a clients' perspective. Especially the initial phase, e.g., what to do if a client starts up for the 1st time and wants to check for updates, is missing in the documentation. I've entered them in a single issue, I can split them of to separate issues if needed...

For example, what should initially be available for the client-updater to initiate an update? Only the root keys (if so, which ones: all of them, or only the root key itself?), or the 'root.json' file? Or should the metadata of all roles be initially supplied? I think it is presumed that an initial version of all metadata is present, but it might be good to make this explicit in the specification.

Another shortcoming is the details on how client-updater workflow should do its update: the spec states that ``if at any point in the following process there is a problem (...) the Root file is downloaded and the process starts over''. Aside from the potential DoS that could lead from this for a client (it might be fed with bogus metadata over and over again, so how many times should it retry this?), it also implies that the local metadata is no longer to be trusted which, if true, could be used as an attack vector. Suppose the following scenario: an adversary has control over the connection by which a client connects to the update server. He mangles the contents of Timestamp file which is detected by the client updater. This causes it to restart the update process with downloading the Root file again, which is now allowing the adversary to inject its own properly signed Root file. The client updater is now confronted with a problem: it gets valid metadata that is not signed by the root keys it knows, nor does it list the keys it currently trusts. This problem is mitigated by enforcing that new versions of Root files should always be cross-signed by the current keys and possibly the new keys. So, clients should accept a new Root file only if, and only if, it is signed by the keys it knows (and already trusts, thus not using the keys listed in the Root file for this!), it lists the current keys it trusts, and has a version that is strictly greater than its own Root file. These checks are subtly different than for other the other files. While this information is present in the spec, it should be made really explicit that this is a strict requirement for client updaters to implement.

What is also not really well described is the workflow for validating the metadata that is available locally: it should be checked for expiration and its signature should be verified. If this fails: first try to download the file again and recheck or always start completely from the beginning with a new Root file?

Also, it would be good to mention that clients are required to have a stable clock(source) in order to correctly verify timestamps. That said, would it not be better if the creation timestamp for metadata files is included in the file? This would allow client updater to no longer rely on information obtained from the webserver to determine whether files are "newer".

[vladimir-v-diaz]

Thank you for the feedback. We agree that the specification is missing critical information in places. Members of the Industrial Haskell Group working to integrate TUF with Haskell's central package archive recently made similar comments after reviewing the specification!

For example, what should initially be available for the client-updater to initiate an update? Only the root keys (if so, which ones: all of them, or only the root key itself?), or the 'root.json' file? Or should the metadata of all roles be initially supplied? I think it is presumed that an initial version of all metadata is present, but it might be good to make this explicit in the specification.

The metadata of all the roles can be initially supplied, but it's not required. At a minimum, the root.json should initially be available for the client to initiate an update. Unfortunately, it appears we don't explicitly state so in the specification. The reference implementation does mention it:

https://github.com/theupdateframework/tuf/blob/develop/tuf/client/updater.py#L227-L247

root.json contains all of the keys for the top-level roles (timestamp.json, targets.json, snapshot.json, and root.json). The client will initially trust these keys and update them when required.

You have a good understanding of the other issues, and we'll be updating the specification to address them.