Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify optional attributes #165

Merged
merged 6 commits into from
Sep 7, 2021

Conversation

MVrachev
Copy link
Contributor

@MVrachev MVrachev commented May 31, 2021

This pr merges changes from #157, #158, and #162 into one for an easier review process and
merging (considering we have to bump the version on each merge)
and closes #156.

This pr makes three changes

  • make delegations optional
  • make consistent_snapshot optional
  • clarify which of paths and path_hash_prefixes can be used and when

Nowhere in the spec, we clarify that delegations is an optional field
in the targets, metadata file which is implied by the file format scheme showed for targets here.

From chapter 6.2.1 in the tuf specification (version 1.019)

Finally, the root metadata should write the Boolean
"consistent_snapshot" attribute at the root level of its keys of
attributes.
If consistent snapshots are not written by the repository,
then the attribute may either be left unspecified or be set
to the False value. Otherwise, it must be set to the True value.

The above implies that there could be repositories with root metadata
without CONSISTENT_SNAPSHOT.
Clarify that, but phrase it so it's clear this should be included
in new implementations.

Finally, clarify paths and path_hash_prefixes in delegations, because
currently, it's not properly defined which of these options can be used
to create a valid target file:

  • BOTH paths and path_hash_prefixes
  • ONLY ONE of paths and path_hash_prefixes
  • NONE of paths and path_hash_prefixes

With this change, I aim to define clearly that a valid target file will
contain ONLY ONE or NONE of them.

Nowhere in the spec, we clarify that "delegations" is an optional field
in the targets metadata file.
This is a possible reason why (at the time of writing this commit) in
the TUF python reference implementation "delegations" is still a
required field.

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
From chapter 6.2.1 in the tuf specification (version 1.019)
"Finally, the root metadata should write the Boolean
"consistent_snapshot" attribute at the root level of its keys of
attributes. If consistent snapshots are not written by the repository,
then the attribute may either be left unspecified or be set
to the False value. Otherwise, it must be set to the True value."

The above implies that there could be repositories with root metadata
without CONSISTENT_SNAPSHOT.
Clarify that, but phrase it so it's clear this should be included
in new implementations.

For context:
https://theupdateframework.github.io/specification/latest/index.html#writing-consistent-snapshots

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Clarify "paths" and "path_hash_prefixes" in delegations, because
currently, it's not properly defined which of these options can be used
to create a valid target file:
- BOTH paths and path_hash_prefixes
- ONLY ONE of paths and path_hash_prefixes
- NONE of paths and path_hash_prefixes

With this change, I aim to define clearly that a valid target file will
contain ONLY ONE of them or NONE of them.

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
@MVrachev MVrachev changed the title Clarify optional Clarify optional attributes May 31, 2021
@MVrachev
Copy link
Contributor Author

MVrachev commented Jun 7, 2021

While working on TUF I noticed that in TUF we have hardcoded a role2.json file (which is a delegation of role1.json which on another hand is delegated in targets.json) not without delegations at all,
but with empty keys dict and roles list. You can see the file here: https://github.com/theupdateframework/tuf/blob/develop/tests/repository_data/repository/metadata/role2.json

Is that what you meant by this in the spec here:

image

PS: Tagging people who I hope have the historical context: @trishankatdatadog, @joshuagl.

@trishankatdatadog
Copy link
Member

While working on TUF I noticed that in TUF we have hardcoded a role2.json file (which is a delegation of role1.json which on another hand is delegated in targets.json) not without delegations at all,
but with empty keys dict and roles list. You can see the file here:

Good catch. Seems weird, but shouldn't be illegal.

tuf-spec.md Outdated Show resolved Hide resolved
@mnm678
Copy link
Collaborator

mnm678 commented Sep 7, 2021

@MVrachev can you set the version to 21

@mnm678
Copy link
Collaborator

mnm678 commented Sep 7, 2021

21

actually, can you make it 22

Co-authored-by: Trishank Karthik Kuppusamy <trishank.kuppusamy@datadoghq.com>
joshuagl
joshuagl previously approved these changes Sep 7, 2021
@mnm678 mnm678 merged commit 8dafd00 into theupdateframework:master Sep 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Clarify "paths" and "path_hash_prefixes" in delegations
4 participants