Skip to content

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

Open

Description

@dennisvang

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).

Activity

  1. changed the title [-]Should signed.version be incremented every time a role is re-signed?[/-] [+]Must signed.version be incremented every time a role is re-signed?[/+] on Jun 8, 2022
  2. jku commented on Jun 8, 2022

    @jku
    Member

    Good point, stuff like this would make the docs much better. I believe any change to published signed metadata should lead to version bump: otherwise clients can't know when they need to download new metadata (in the case that they already have the previous version downloaded).

    The only modification to metadata that doesn't need this that I could imagine is adding signatures... but even that seems safe only before the metadata is made public to clients (otherwise some clients could have fewer signatures and then signing keys might get changed and who knows how that would end).

  3. lukpueh commented on Jun 8, 2022

    @lukpueh
    Member

    Good question!

    The spec has recently been updated to be a bit more specific about how the client should deal with new metadata that has the same version as the trusted one (see theupdateframework/specification#209).

    In case they [versions] are equal, discard the new
    timestamp metadata and abort the update cycle. This is normal and it
    shouldn't raise any error. The reason for aborting the update process is that
    there shouldn't be any changes in the content of this, or any other metadata
    files too, considering it has the same version as the already trusted one.

    Parts of this are still being discussed in theupdateframework/specification#114

  4. dennisvang commented on Jun 8, 2022

    @dennisvang
    Author

    ... I believe any change to published signed metadata should lead to version bump: ...

    @jku Yes, that certainly makes sense. Thanks for clarifying! :-)

  5. lukpueh commented on Jun 8, 2022

    @lukpueh
    Member

    ... I believe any change to published signed metadata should lead to version bump: ...

    @jku Yes, that certainly makes sense. Thanks for clarifying! :-)

    In the case of targets and snapshot metadata it also makes sense to bump if only the signatures are changed, because their file hashes could be listed in other metadata (snapshot can list targets metadata file hashes, and timestamp can list snapshot metadata file hashes).

  6. dennisvang commented on Jun 8, 2022

    @dennisvang
    Author

    In the case of targets and snapshot metadata it also makes sense to bump if only the signatures are changed, because their file hashes could be listed in other metadata (snapshot can list targets metadata file hashes, and timestamp can list snapshot metadata file hashes).

    @lukpueh Thanks for pointing that out.

    So, would it be correct to say that the safest rule-of-thumb is to always bump the version whenever someone signs a role?

  7. lukpueh commented on Jun 8, 2022

    @lukpueh
    Member

    bump the version whenever someone signs a role

    ... and publishes it for someone to consume.

    I would say.

  8. dennisvang commented on Jun 8, 2022

    @dennisvang
    Author

    bump the version whenever someone signs a role

    ... and publishes it for someone to consume.

    where the consumer would be either a tuf client or another key-owner?

    (sorry for going on about this)

  9. lukpueh commented on Jun 8, 2022

    @lukpueh
    Member

    Ha, excellent follow-up question. I was only thinking of a client.

    For threshold signing we actually must not bump the version on each signature. Otherwise we'd sign different content each time and would never reach the desired threshold.

  10. dennisvang commented on Jun 9, 2022

    @dennisvang
    Author

    In the case of targets and snapshot metadata it also makes sense to bump if only the signatures are changed, because their file hashes could be listed in other metadata (snapshot can list targets metadata file hashes, and timestamp can list snapshot metadata file hashes).

    Still trying to figure this out...

    Suppose timestamp lists the hash for the snapshot file, and only the signatures for snapshot are changed (for some reason). This means the snapshot "signed" portion does not change, but the snapshot file hash does change. Thus, the "signed" portion for timestamp changes. Then wouldn't it make sense to bump the signed.version for timestamp only, and leave the signed.version for snapshot untouched?

  11. JustinCappos commented on Jun 9, 2022

    @JustinCappos
    Member
  12. MVrachev commented on Jun 9, 2022

    @MVrachev
    Collaborator

    In the case of targets and snapshot metadata it also makes sense to bump if only the signatures are changed, because their file hashes could be listed in other metadata (snapshot can list targets metadata file hashes, and timestamp can list snapshot metadata file hashes).

    Still trying to figure this out...

    Suppose timestamp lists the hash for the snapshot file, and only the signatures for snapshot are changed (for some reason). This means the snapshot "signed" portion does not change, but the snapshot file hash does change. Thus, the "signed" portion for timestamp changes. Then wouldn't it make sense to bump the signed.version for timestamp only, and leave the signed.version for snapshot untouched?

    Changing the signature of snapshot without changing the signed portion means that there is a change in the snapshot key used for singing. I think you will want to have a new version of snapshot in this case as you want to signal to your clients that there is a change in the keys used. This is useful in the case of snapshot key/keys compromise when you will want to rotate the keys with new ones.

  13. dennisvang commented on Jun 9, 2022

    @dennisvang
    Author

    ... as you want to signal to your clients that there is a change in the keys used. This is useful in the case of snapshot key/keys compromise when you will want to rotate the keys with new ones.

    @MVrachev Doesn't the client handle this automatically, because the root role is updated at the beginning of the client workflow?

    As I understand it (perhaps wrongly...), the spec suggests that the signed.version for snapshot is only read after verifying the signatures, see e.g. 5.5 steps 3 and 4. The hash for snapshot would have changed, but that would be taken care of by the updated timestamp file, which would have been downloaded first (5.4).

    Side note: Not sure if it matters for the current discussion, but I'm not considering consistent snapshots in this example, so the snapshot metadata file doesn't have a version in the filename.

  14. dennisvang commented on Jun 10, 2022

    @dennisvang
    Author

    If we consider the metadata object (basically the content of a metadata file):

    {
      "signed" : ROLE,
      "signatures" : [
        { "keyid" : KEYID,
          "sig" : SIGNATURE }
          , ... ]
    }
    

    It is clear that the "signatures" element depends on the "signed" element: We sign off on the content of "signed", which includes a specific "version".

    But, the other way round, shouldn't the "signed" element always remain independent of the "signatures" element (within that same metadata object)?

    In other words, being a naive user, I would expect that an isolated change in the "signatures" element (for whatever reason) should never cause a change in the "signed" element (such as a version bump) of the same metadata object. On the other hand, it could (or should?) cause a version bump in the "signed" element of other, dependent, metadata objects (once it is published).

    For example, an isolated change in the "signatures" element for snapshot should not cause a version bump for snapshot itself, but could lead to a version bump in timestamp, but only if timestamp contains the file hash etc. for snapshot.json.

    Please correct me if I'm wrong here. :-)

  15. lukpueh commented on Jun 10, 2022

    @lukpueh
    Member

    Your mental model seems right to me, maybe it works better with what we suggested above if we shift the causality a bit...

    So I wouldn't say that a change in the independent signatures element causes a change in the signed element, but rather that only a version bump in the signed element causes the client to consider it as new metadata. Does that make sense?

  16. lukpueh commented on Jun 10, 2022

    @lukpueh
    Member

    @MVrachev:

    Changing the signature of snapshot without changing the signed portion means that there is a change in the snapshot key used for singing.

    This is a likely but not the only reason for a change in signatures.

    I think you will want to have a new version of snapshot in this case as you want to signal to your clients that there is a change in the keys used.

    In case of a timestamp or snapshot key rotation in root metadata, we delete the trusted versions of those metadata files to allow recovery from a potential ffw attack. So in that case the version bump isn't actually required. :)

  17. dennisvang commented on Jun 10, 2022

    @dennisvang
    Author

    @lukpueh Yes, thanks, I think that makes sense.

    I'm still looking for a clear guideline. Something like the following, perhaps?

    The "signed" version for a metadata object must be incremented if, and only if, the "signed" content has changed w.r.t. the latest published version of that metadata object.

  18. lukpueh commented on Jun 10, 2022

    @lukpueh
    Member

    Maybe we can phrase it with regards to the user?

    The "signed" version for a metadata object must be incremented if, any client downloader should consider it as new trusted metadata.

  19. dennisvang commented on Jun 10, 2022

    @dennisvang
    Author

    The "signed" version for a metadata object must be incremented if, any client downloader should consider it as new trusted metadata.

    That sounds better, and looking at this from the client workflow perspective does provide a better understanding of how the "version" is actually used. Although I do think this is a bit less explicit.

    From the repository perspective, I was thinking along these lines (see if-condition):

    ...
    # load metadata from file
    snapshot = Metadata.from_file(snapshot_path)
    original_snapshot_signed = copy.deepcopy(snapshot.signed)
    # make some changes to the signed metadata (or maybe not, if we're only threshold signing)
    ...
    # bump version if necessary (see tuf.api.metadata.Signed.__eq__)
    version_bumped = snapshot.signed.version > original_snapshot_signed.version
    if snapshot.signed != original_snapshot_signed and not version_bumped:
        snapshot.signed.version += 1
    # sign and persist
    ...
  20. lukpueh commented on Jun 13, 2022

    @lukpueh
    Member

    So this translates to "bump version right before sign/persist (for publication) if signed part has changed, unless the change already includes a version bump"? I think this makes sense as a rule of thumb.

  21. dennisvang commented on Jun 13, 2022

    @dennisvang
    Author

    @lukpueh Yes, I think that translation covers it.

  22. added
    repositoryRelated to the repository implementation
    documentationDocumentation of the project as well as procedural documentation
    on Jun 15, 2022
  23. lukpueh commented on Jun 15, 2022

    @lukpueh
    Member

    This issue should be resolved as part of #1136 either in code or in documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationDocumentation of the project as well as procedural documentationrepositoryRelated to the repository implementation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions