theupdateframework / theupdateframework/python-tuf

Must signed.version be incremented every time a role is re-signed?

Open
#2,020 21 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation repository
Dominant language
Python
Stars
1.7k
Forks
304
Avg merge
1d 2h
Merged PRs (30d)
17

Description

Description of issue or feature request:

After reading the TUF specification and studying the basic_repo.py example, one thing remains unclear to me:

When exactly do we need to increment signed.version?

It is clear that we need to increment the signed.version after e.g. adding a new target, as detailed in the basic_repo.py example.

However, what if we only modify signed.expires, after a role has expired, without changing anything else? Do we also need to increment signed.version in that case? That would imply e.g. the version of timestamp is incremented every time it is re-signed.

In general, do we need to increment a role's signed.version every time we re-sign that role, without exception?

Current behavior:

It is not explicitly clear from the documentation when signed.version needs to be incremented.

Expected behavior:

It would be very helpful if the documentation/specification could clarify this point explicitly.

Perhaps the basic_repo.py example could also show a snippet where an expired timestamp is re-signed (without any changes to the root, targets, or snapshot metadata).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked TUF specification's timestamp file-format section, then compare the signed.version handling in examples/repo_example/basic_repo.py and the referenced tuf/api/metadata.py locations. Review the existing discussion before deciding on wording. Done means the documentation explicitly explains when re-signing requires a version increment and includes the requested expired-timestamp example.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, security
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.