specification
specification copied to clipboard
theupdateframework
Secondary literature with detailed rationale and recommendations
It could be valuable for potential adopters of TUF if there were some documentation beyond the specification, published papers and conversations captured on GitHub, that goes into detail about certain decisions, makes recommendations where the specification deliberately leaves things open and points to open implementations of the specification (i.e. Notary and PEP 458) as examples of the context for the various decisions that must be made when applying the TUF specification to a scenario.
The spec is a good document but provides several points where choices must be made without providing any explanation or guidance.
The papers which motivated various spec decisions and changes provide interesting reading but can be a little dense when trying to understand a nuance of the specification where the context for a decision may be difficult to elicit and, furthermore, the papers are a static document, unlike the specification itself.
In contrast to the specification, which should only say “do XYZ”, this additional document could say things like “do XYZ because foo, bar, baz” or “do X if your situation is quux (akin to projects ABC) or do Y if it is thud (akin to projects DEF)”.
cc @lukpueh
This is a good suggestion. We have a document like this for the automotive variant of TUF (Uptane) called the Deployment Considerations ( e.g., see part of it here: https://uptane.github.io/deployment-considerations/repositories.html ).
We should think about how to get relevant information back into TUF.
On Fri, Feb 14, 2020 at 9:41 AM Joshua Lock [email protected] wrote:
It could be valuable for potential adopters of TUF if there were some documentation beyond the specification, published papers and conversations captured on GitHub, that goes into detail about certain decisions, makes recommendations where the specification deliberately leaves things open and points to open implementations of the specification (i.e. Notary and PEP 458) as examples of the context for the various decisions that must be made when applying the TUF specification to a scenario.
The spec is a good document but provides several points where choices must be made without providing any explanation or guidance.
The papers which motivated various spec decisions and changes provide interesting reading but can be a little dense when trying to understand a nuance of the specification where the context for a decision may be difficult to elicit and, furthermore, the papers are a static document, unlike the specification itself.
In contrast to the specification, which should only say “do XYZ”, this additional document could say things like “do XYZ because foo, bar, baz” or “do X if your situation is quux (akin to projects ABC) or do Y if it is thud (akin to projects DEF)”.
cc @lukpueh https://github.com/lukpueh
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/theupdateframework/specification/issues/91?email_source=notifications&email_token=AAGROD6UVKV5YHPWH2Z2Z63RC2URLA5CNFSM4KVJM5PKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4INS2TYA, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGRODZZ4JPGC4QLAQL2PZLRC2URLANCNFSM4KVJM5PA .
Also see secondary literature worthy discussion by @mnm678 and @trishankatdatadog about when to use (not use) optional length/hashes fields in timestamp and snapshot metadata.
Trishank shared some wisdom during a PEP 458/Warehouse integration discussion that I think is worth capturing as a recommendation in the secondary literature.
Paraphrasing his advice:
keep a pinned trusted copy of the root metadata, at least the hash, in the repository code so that there's a trusted base to build from
@trishankatdatadog please correct me if I didn't quite capture that right.
@trishankatdatadog please correct me if I didn't quite capture that right.
Absolutely right, thank you 🙏
Other potential secondary literature topics:
- how to initialise trust from a local copy of the metadata #108
- techniques for recovering from an interrupted update #69, or how to interpret the following statement from the detailed client workflow:
Note: If a step in the following workflow does not succeed (e.g., the update is aborted because a new metadata file was not signed), the client should still be able to update again in the future. Errors raised during the update process should not leave clients in an unrecoverable state.
Another topic to include:
- How to handle races with threshold signing theupdateframework/tuf#969
- Provide some guidance for the application set value of Y (maximum number of new root files to download) in 5.3.3 (see related issue in python-tuf https://github.com/theupdateframework/python-tuf/issues/1577)
- Repository publishing recommendations: atomic/single transaction OR bottom-up (with caveats about raciness), as discussed in #223
Validating root metadata before snapshoting, as mentioned in theupdateframework/go-tuf#292
Section 5.4 of the Mercury paper (section 5.4) suggests that a package manager bundle both root and snapshot metadata in order to offer some rollback protection.