Rewriting the workflow to call out to sub-sections

[erickt]

The TUF spec is written in a prose form, especially the update workflow. One of the challenges with this that we have duplicated paragraphs that describe essentially the same thing. For example:

2.1. Check signatures. The new timestamp metadata file must have been signed by a threshold of keys specified in the trusted root metadata file. If the new timestamp metadata file is not properly signed, discard it, abort the update cycle, and report the signature failure. ... 3.2. Check signatures. The new snapshot metadata file MUST have been signed by a threshold of keys specified in the trusted root metadata file. If the new snapshot metadata file is not signed as required, discard it, abort the update cycle, and report the signature failure. ... 4.2. Check for an arbitrary software attack. The new targets metadata file MUST have been signed by a threshold of keys specified in the trusted root metadata file. If the new targets metadata file is not signed as required, discard it, abort the update cycle, and report the failure.

Note each section has a slight change from each other, which happens as small corrections happen in one, but we forget to fix it in the others. Instead, I think it's worth considering restructuring the workflow (and possibly the rest of the doc) to be more in the style of the whatwg specs (such as https://url.spec.whatwg.org/), where we call out to sub-sections to implement these major steps. For example, parsing the signatures could be written as:

2.1 Check the signatures.

1. Let sig_result be the result of check signatures with metadata being the new timestamp metadata, role being timestamp, and root being the trusted root metadata.
2. If sig_result is failure, then return failure. ...

Check signatures:

The signature checker takes a metadata metadata, and a role type role, and a root metadata.

1. Canonicalize the metadata as canonical_metadata_bytes.
2. For each signature sig in the metadata`'s signature field:
   1. If sig is in a processed_sig set, skip the signature.
   2. If it signed canonical_metadata_bytes. Increment a threshold counter.
3. If threshold counter is less than role's threshold in the root metadata, return failure.

I think this sort of thing would really be helpful in making sure we don't make subtle copy-paste errors when changing the spec, and make it much easier on a client library to implement the spec correctly.

[trishankatdatadog]

+1

[lukpueh]

➕ from my side. On a mildly related note, I wonder if there are any good cross-referencing plugins for GitHub markdown. Manually updating section numbers and references is really tedious.

[joshuagl]

+1 to both @erickt and @lukpueh's suggestion. It is starting to feel increasingly difficult to keep the spec coherent, ideally section numbers and cross-referencing would be much simpler to keep accurate.

Splitting out duplicated procedures into sub-sections seems like a usability win for the reader, but may be even more prone to cross-referencing issues than the current prose format.

[trishankatdatadog]

Maybe we should just drop Markdown and use something more standards-specific. There are a few tools out there for this. We should shop around.

[erickt]

I've started experimenting with the tool bikeshed, which is the tool whatwg and a few other standards committees use for their specs. I made some slight format changes to the TUF spec in order to make bikeshed happy, which renders out here. I haven't tried playing with any more of the advanced features of bikeshed yet though, but it certainly seems like an interesting tool.

[joshuagl]

bs looks good, thanks for identifying it as a potential solution and starting to PoC converting the spec @erickt !

I'd like to help with this effort. Ideally we would get #118 and #122 merged first, then make a concerted effort to port the specification to bikeshed. How does that sound?