Write a bit more about the two modules, hide the actual TOC to not
repeat (and not have sphinx complain about missing items in TOC)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
This allows using existing documentation in the published documentation
without
* moving the existing docs (which would break external links)
* tricks like symlinks that create issues with relative links
Put the api reference files into a subdirectory to avoid polluting the
main docs/ directory.
Include "Installation" and "Instructions for Contributors" in the
published documentation.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Remove link to outdated roadmap
* Link to maintainers file in the same way as two lines earlier
* Fix formatting issues with code blocks
These fixes allow the installation rst to be used from sphinx sources
and from docs root.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Improve content
* Make ngclient Updater __init__() visible in docs
* Remove "legacy implementation" (except for the note on API stability)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
I was looking at how can we simplify or split test_api.py when I noticed
that the test cases covered by those two test functions are already
covered in the test_metadata_serialization.py module in the
"invalid_keys" and "invalid_roles" datasets.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
- New 'docs' environment in tox enables
building the sphinx documentation in isolation.
- New requirements-docs.txt.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Add .rst source files for building documentation with
'sphinx'. The two mandatory files are conf.py containing
the build configuration and the master doc file index.rst.
Sphinx uses 'autodoc' to automatically include docstrings.
'autodoc' imports the modules and needs TUF installed in
the environment.
The following command will generate the documentation from the
source files in an html format:
`sphinx-build -b html docs/sphinx/source docs/sphinx/build/html`
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
A new warning appeared from pylint when calling "tox -e lint" on the
"develop" branch with id "unspecified-encoding",
I read about the warning and it make sense.
Read more about the warning here:
https://github.com/PyCQA/pylint/issues/3826
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Those tests are needed to cover use cases when syntatcticly as
standalone objects the metadata classes and their helper classes defined
in tuf/api/metadata.py are valid even if they cannot be verified.
An example where an object is valid, but cannot be verified is
if we have a Role instance with an empty list of "keyids".
This instance is valid and can be created, but cannot be verified
because there is a requirement that the threshold should be above
1, meaning that there should be at least 1 element inside the "keyids"
list to complete successful threshold verification.
The situation is the same for the rest of the tests I am adding to this
commit:
- Root object without keys
- Root object without roles
- DelegationRole object with empty "keyids"
- DelegationRole object with an empty list of "paths"
- DelegationRole object with an empty list of "path_hash_prefixes"
all of these objects can be instantiated, but cannot complete
successfully threshold verification.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Test metadata (de)serialization with input data containing containers
with zero or more elements.
Here is the status for the different use cases:
Root keys:
- many keys: added
Root roles:
- many roles: added
Root role keyids:
- many keids: already added in https://github.com/theupdateframework/tuf/pull/1481
MetaFile hashes:
- many hashes: already tested
- zero hashes: added. Testing as invalid test case.
Timestamp meta:
- zero elements: already tested
- many elements: added
Snapshot meta:
- zero items: added
- many items: added
Delegation keys:
- many keys: added
Delegation role keyids:
- many keyids: added
Delegation role paths:
- many paths: already tested
Delegation role path_hash_prefixes:
- many path_hash_path_prefixes: already tested
Delegation roles:
- zero roles: added
- multiple roles: added
Targets targets:
- zero items: already tested
- multiple items: added
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Spec does not explicitly say so but the intent is that a snapshot
metadata can be trusted for rollback protection checks of newer
snapshots even if current snapshot version does not match the version
in current timestamp meta.
Only do the snapshot version check for the "final" snapshot by doing it
when targets is updated.
Improve test names and comments.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
While this is not explicitly said in the spec, the intention is that
expired timestamp and snapshot should be used for rollback protection
checks on newer timestamp/snapshot (but not for anything else).
Move the expiry checks to the "next" metadata update: timestamp expiry
is checked when snapshot is loaded, and snapshot expiry is checked
when targets is loaded.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
The usefulness was debatable to begin with, and now that it has become
clear that rollback protection requires a second "final verification"
step for all three root, timestamp and snapshot it is clear that
root_update_finished() is not good design.
update_root() still accepts expired root metadata but now the final
root expiry is checked when the "next" metadata (timestamp) is loaded.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Add support for prefixing targets with their hashes when downloading or
using HASH.FILENAME.EXT as target names.
The introduction of prefix_targets_with_hash was necessary, because
there are use cases like Warehouse where you could use
consistent_snapshot, but without adding a hash prefix to your targets.
When prefix_targets_with_hash is set to True, target files conforming
the format HASH.FILENAME.EXT will be downloaded from the server, but
they will be saved on the client side without their hash prefixes or
FILENAME.EXT.
This makes sure the client won't understand the usage of
prefix_targets_with_hash.
Still, if you want to use HASH.FILENAME.EXT as target names when
downloading, then additionally you need to provide consistent_snapshot
set to True in your root.json. The reason is that the specification uses
consistent_snapshot for the same purpose:
"If consistent snapshots are not used (see § 6.2 Consistent snapshots),
then the filename used to download the target file is of the fixed form
FILENAME.EXT (e.g., foobar.tar.gz). Otherwise, the filename is of the
form HASH.FILENAME.EXT
(e.g., c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz),
where HASH is one of the hashes of the targets file listed in the
targets metadata file found earlier in step § 5.6 Update the targets role.
In either case, the client MUST write the file to non-volatile
storage as FILENAME.EXT."
The same behavior of using two flags is used in the legacy code when
calling tuf.client.updater.download_target() in a repository using
prefix_targets_with_hash and consistent_snapshot.
See chapter 5.7.3:
https://theupdateframework.github.io/specification/latest/index.html#fetch-target
By default, prefix_targets_with_hash is set to true to make it easier
to the user to provide uniquely identifiable targets file names by
using consistent_snapshot set to True.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
When we use Metadata, it is helpful if the specific signed type (and all of
the signed types attribute types are correctly annotated. Currently this is
not possible.
Making Metadata Generic with constraint T, where
T = TypeVar("T", "Root", "Timestamp", "Snapshot", "Targets")
allows these annotations. Using Generic annotations is completely
optional so all existing code still works -- the changes in test code
are done to make IDE annotations more useful in the test code, not
because they are required.
Examples:
md = Metadata[Root].from_bytes(data)
md:Metadata[Root] = Metadata.from_bytes(data)
In both examples md.signed is now statically typed as "Root" allowing IDE
annotations and static type checking by mypy.
Note that it's not possible to validate that "data" actually contains a
root metadata at runtime in these examples as the annotations are _not_
visible at runtime at all: new constructors would have to be added for that.
from_file() is now a class method like from_bytes() to make sure both
have the same definition of "T" when from_file() calls from_bytes():
This makes mypy happy.
Partially fixes#1433
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Give 'role_names' the more verbose description
'delegations_to_visit'.
Add some comments and docstrings.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
The specification does not state clearly what is the
behaviour when none of delegation's "paths" and
"path_hash_prefixes" is set. See #1497.
Until this issue is clarified, copy current
Updater which raises an error in such case.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Rename to DelegatedRole.is_delegated_path and
return a boolean flag instead of the role's name.
Minor comments and code style improvements.
Some code simplification.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Replace the helper verify_with_threshold() with
the newly implemented method Metadata.verify_delegate.
Add an aditional type annotation helping the IDE.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
* Update CLI.md
Update the suggested command template for "trust keys", to make it consistent with other examples.
Signed-off-by: hosseinsia <hossein.siadati@datadoghq.com>
* Update docs/CLI.md
Remove the + to avoid confusion.
Co-authored-by: Martin Vrachev <martin.vrachev@gmail.com>
Signed-off-by: hosseinsia <hossein.siadati@datadoghq.com>
Co-authored-by: Martin Vrachev <martin.vrachev@gmail.com>
Instead of using general abstract modification functions embed smaller
modification functions inside each test where it's needed and
create modify_metadata function that does all of the common stuff like:
- instantiating a metadata object
- calling the modification function
- signing the modified object
- serializing back to bytes.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
