Docs: Add repository tutorial based on metadata API #1685

lukpueh · 2021-11-18T12:54:38Z

[EDIT 11/23/2021: remove draft status and update PR description]
[EDIT 11/25/2021: remove reviewer question about test, the PR includes one]

Fixes #1673

Description

Add an excessively commented python script to demonstrate repository creation/operation using only the low-level metadata API.

Context
As 'repository_tool' and 'repository_lib' are being deprecated, repository metadata must to be created and maintained manually using the low-level Metadata API. The example code in these files shall serve as temporary replacement until a new repository tool is available.

Contents

creation of top-level metadata
target file handling
consistent snapshots
key management
top-level delegation and signing thresholds
target delegation
in-band and out-of-band metadata signing
writing and reading metadata files
root key rotation

Questions for reviewers

Is this readable enough? Should this rather be a markdown document?
Is it too broad? Should we move some usage scenarios to different files?
E.g. hashed bin delegation will be in a separate file (see follow-up PR)
How can we demonstrate validity? With a TrustedMetadata example?
How can we demonstrate usage? With a client example follow-up?

Please verify and check that the pull request fulfills the following requirements:

The code follows the Code Style Guidelines
Tests have been added for the bug fix or new feature
Docs have been added for the bug fix or new feature

sechkova

Thanks for the refreshment exercise :) I left some comments on the text itself.
I don't think the example is too broad, having everything at one place seems like a good idea. Maybe in time, more detailed examples can be added for some trickier cases (complex delegations, key rotations ...).

sechkova · 2021-11-19T13:30:45Z

examples/repo_example/basic_repo.py

+
+# Common fields
+# -------------
+# All roles have the same metadata container format. On the top-most level,


Maybe we can somehow point to the Metadata class here?

sechkova · 2021-11-19T13:37:21Z

examples/repo_example/basic_repo.py

+# from which a client would download the target file.
+target_local_path = os.path.abspath(__file__)
+target_file_path = os.path.basename(__file__)
+target_file_info = TargetFile.from_file(target_file_path, target_local_path)


I have no good suggestion for improvement but these paths seem confusing. I admit I had to read it twice even though I was supposed to know what is going on 😁 Maybe an example path and/vs URL could help.

I can see that how it confusing. I'll try to better explain/exemplify those two paths.

sechkova · 2021-11-19T13:43:17Z

examples/repo_example/basic_repo.py

+# The timestamp role guarantees freshness of the repository metadata. It does
+# so by listing the latest snapshot (which in turn lists all the latest
+# targets) metadata. Choosing a short expiration interval, requires clients to
+# often re-download timestamp and thus immediately detect if new target files


Doesn't the client always try to download timestamp?

Ha! So much for "fully internalized spec". Thanks for catching this. I'll reword.

sechkova · 2021-11-19T14:00:34Z

examples/repo_example/basic_repo.py

+# Just assume we do out-of-band signing for keys we don't have
+for key in [keys["root"], another_root_key] + new_root_keys:
+ roles["root"].sign(SSlibSigner(key), append=True)
+


I think the part "signing with a threshold of old keys AND a threshold of the new keys" needs an emphasis.

➕ I absolutely agree.

coveralls · 2021-11-23T14:04:13Z

Pull Request Test Coverage Report for Build 1515912733

69 of 69 (100.0%) changed or added relevant lines in 1 file are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.1%) to 97.578%

Totals
Change from base Build 1503123861:	0.1%
Covered Lines:	4029
Relevant Lines:	4113

💛 - Coveralls

lukpueh · 2021-11-23T14:11:39Z

Thanks for your review, @sechkova! I just finalised the example texts and squashed all commits into one. Your comments should be addressed in another commit on top of that for re-review convenience, i.e. 2fc5945.

I'd appreciate another look. Also see the updated PR description, especially the "Questions for reviewers".

lukpueh · 2021-11-25T11:13:30Z

I just added very basic testing that runs the example script using exec and checks if the metadata files were created as expected. It currently only checks for file existence, but it wouldn't be hard to add more thorough inspection of the created files.

Note that the test class is intended to be re-used for a similar example script that I have in the pipe.

sechkova

Would be nice if more people provide feedback but you have my approval 😁
I also filled in the questionnaire.

Is this readable enough? Should this rather be a markdown document?

No strong opinion here, I'm ok with this one

Is it too broad? Should we move some usage scenarios to different files?
E.g. hashed bin delegation will be in a separate file (see follow-up PR)

Nope, I like it,

How can we demonstrate validity? With a TrustedMetadata example?

Seems like the options are either a full Updater with a server or using TrustedMetadata by providing it with the metadata files as bytes. The second option sounds more interesting to me :)

How can we demonstrate usage? With a client example follow-up?

I have nothing better to propose.

examples/repo_example/basic_repo.py

joshuagl

Thanks for this @lukpueh, beautiful work – very clear example and a testament to the Metadata API. 🎉

Is this readable enough? Should this rather be a markdown document?

To me this is very readable, appreciate the detail and care here.

Is it too broad? Should we move some usage scenarios to different files?

LGTM as is. Covers the common cases, I think.

How can we demonstrate validity? With a TrustedMetadata example?

Implicit in the below? And future work once the proposed repository API validation piece is implemented? i.e. I think this is a solid submission as-is.

How can we demonstrate usage? With a client example follow-up?

Could be a simple follow-on that runs a http server over the data generated here and uses ngclient to fetch the python file?

examples/repo_example/basic_repo.py

joshuagl · 2021-11-25T14:59:36Z

examples/repo_example/basic_repo.py

+# from within other metadata, and thus allows for repository consistency in
+# addition to protecting against rollback attacks.
+#
+# The expiry date, protects against freeze attacks and allows for implicit key


consistency:

Suggested change

# The expiry date, protects against freeze attacks and allows for implicit key

# The 'expiry' date protects against freeze attacks and allows for implicit key

The field name is 'expires'. Should we write "The 'expires' date... "? Does consistency beat grammar? :D
Regardless, I'll remove the stray comma.

🤦 of course.

I think it is better to bind the comments to the variables, maybe:
"The date the metadata 'expires'..." ?

examples/repo_example/basic_repo.py

tests/test_examples.py

jku

LGTM, I think this is fine as the stop gap: it's demonstrating the basic elements that a repository needs to handle, without pretending to actually be a repository implementation.

My reaction to the "is it too broad" question is that we shouldn't put a lot of effort into expanding or splitting it (although the hashed bin example should be useful), if we can push the repository library and its example code (or a repository tool) forward instead...

The repository validation question is more interesting... but even there maybe the answer isn't to expand this tutorial code .

On the usage question: this could be a follow-up issue that is solved when initial versions of both this and the client example are present. Possible solution:

document how to serve the generated directory over http
add a "bootstrap from this root.json" option to the client so it can be used with the generated repository

examples/repo_example/basic_repo.py

tests/test_examples.py

lukpueh · 2021-11-29T10:59:50Z

Thanks for the thorough reviews, @sechkova, @joshuagl and @jku! I addressed your comments in 4327214 and 83764c6 (the latter in response to #1685 (comment)).

May I ask for another quick round of LGTMs? (NOTE: the commits are labeled WIP, because I intend to squash them before merging.)

jku

👍

joshuagl

LGTM, thanks!

examples/repo_example/basic_repo.py

MVrachev

I just read it and liked the comments and comparing that to tuf/repository_tool.py is such an improvement and simplification.
Great work!

As 'repository_tool' and 'repository_lib' are being deprecated, repository metadata must to be created and maintained manually using the low-level Metadata API. The added example code shall serve as temporary replacement until a new repository tool is available. The sample code contains the following repo workflows: - creation of top-level metadata - target file handling - consistent snapshots - key management - top-level delegation and signing thresholds - target delegation - in-band and out-of-band metadata signing - writing and reading metadata files - root key rotation Co-authored-by: Teodora Sechkova <tsechkova@vmware.com> Co-authored-by: Joshua Lock <jlock@vmware.com> Co-authored-by: Jussi Kukkonen <jku@goto.fi> Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>

Adds new test module that executes the basic repo example Python script and checks that it created certain (metadata) files. The test module is tailored for testing similar example scripts. Co-authored-by: Joshua Lock <jlock@vmware.com> Co-authored-by: Jussi Kukkonen <jku@goto.fi> Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>

lukpueh · 2021-11-29T12:31:08Z

Thanks, everyone!

sechkova reviewed Nov 19, 2021

View reviewed changes

kairoaraujo mentioned this pull request Nov 22, 2021

TUF Python Client Example/Tutorial #1675

Merged

3 tasks

lukpueh force-pushed the repo-examples branch from 9b07a45 to 2fc5945 Compare November 23, 2021 13:56

lukpueh changed the title ~~Docs: Add repository tutorial based on metadata API (WIP)~~ Docs: Add repository tutorial based on metadata API Nov 23, 2021

lukpueh marked this pull request as ready for review November 23, 2021 14:05

lukpueh force-pushed the repo-examples branch from 30ab533 to b3665f2 Compare November 25, 2021 11:07

sechkova approved these changes Nov 25, 2021

View reviewed changes

examples/repo_example/basic_repo.py Outdated Show resolved Hide resolved

examples/repo_example/basic_repo.py Show resolved Hide resolved

examples/repo_example/basic_repo.py Outdated Show resolved Hide resolved

joshuagl approved these changes Nov 25, 2021

View reviewed changes

jku approved these changes Nov 29, 2021

View reviewed changes

examples/repo_example/basic_repo.py Outdated Show resolved Hide resolved

tests/test_examples.py Show resolved Hide resolved

lukpueh force-pushed the repo-examples branch from 93cdf24 to 83764c6 Compare November 29, 2021 10:51

jku approved these changes Nov 29, 2021

View reviewed changes

joshuagl approved these changes Nov 29, 2021

View reviewed changes

examples/repo_example/basic_repo.py Outdated Show resolved Hide resolved

MVrachev reviewed Nov 29, 2021

View reviewed changes

lukpueh added 2 commits November 29, 2021 13:25

lukpueh force-pushed the repo-examples branch from 83764c6 to a1531d8 Compare November 29, 2021 12:26

lukpueh merged commit 51248db into theupdateframework:develop Nov 29, 2021

This was referenced Nov 29, 2021

Docs: Add repository tutorial based on metadata API #1673

Closed

doc: basic hash bin delegation repo example + test #1700

Merged

Move linters configurations in pyproject.toml #1699

Merged

Start linting the examples folder #1701

Merged

lukpueh mentioned this pull request Dec 13, 2021

Prepare v0.20.0 #1723

Closed

lukpueh mentioned this pull request Feb 23, 2022

Documentation Overhaul #808

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add repository tutorial based on metadata API #1685

Docs: Add repository tutorial based on metadata API #1685

lukpueh commented Nov 18, 2021 •

edited

Loading

sechkova left a comment

sechkova Nov 19, 2021

sechkova Nov 19, 2021 •

edited

Loading

lukpueh Nov 22, 2021

sechkova Nov 19, 2021

lukpueh Nov 22, 2021

sechkova Nov 19, 2021

lukpueh Nov 22, 2021

coveralls commented Nov 23, 2021 •

edited

Loading

lukpueh commented Nov 23, 2021

lukpueh commented Nov 25, 2021 •

edited

Loading

sechkova left a comment

joshuagl left a comment •

edited

Loading

joshuagl Nov 25, 2021

lukpueh Nov 29, 2021

joshuagl Nov 29, 2021 •

edited

Loading

jku left a comment •

edited

Loading

lukpueh commented Nov 29, 2021

jku left a comment

joshuagl left a comment

MVrachev left a comment

lukpueh commented Nov 29, 2021

	# The expiry date, protects against freeze attacks and allows for implicit key
	# The 'expiry' date protects against freeze attacks and allows for implicit key

Docs: Add repository tutorial based on metadata API #1685

Docs: Add repository tutorial based on metadata API #1685

Conversation

lukpueh commented Nov 18, 2021 • edited Loading

sechkova left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sechkova Nov 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Nov 23, 2021 • edited Loading

Pull Request Test Coverage Report for Build 1515912733

💛 - Coveralls

lukpueh commented Nov 23, 2021

lukpueh commented Nov 25, 2021 • edited Loading

sechkova left a comment

Choose a reason for hiding this comment

joshuagl left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshuagl Nov 29, 2021 • edited Loading

Choose a reason for hiding this comment

jku left a comment • edited Loading

Choose a reason for hiding this comment

lukpueh commented Nov 29, 2021

jku left a comment

Choose a reason for hiding this comment

joshuagl left a comment

Choose a reason for hiding this comment

MVrachev left a comment

Choose a reason for hiding this comment

lukpueh commented Nov 29, 2021

lukpueh commented Nov 18, 2021 •

edited

Loading

sechkova Nov 19, 2021 •

edited

Loading

coveralls commented Nov 23, 2021 •

edited

Loading

lukpueh commented Nov 25, 2021 •

edited

Loading

joshuagl left a comment •

edited

Loading

joshuagl Nov 29, 2021 •

edited

Loading

jku left a comment •

edited

Loading