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.

Sign up for GitHub

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

Added TAP for TUF Version Management #107

Merged
merged 41 commits into from
Aug 18, 2020
Merged

Added TAP for TUF Version Management #107

Changes from 1 commit
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
950dc60
added TAP 12 draft
mnm678 Dec 20, 2018
cc9f318
clarified client update
mnm678 Jan 7, 2019
1622a14
removed tap number for draft tap
mnm678 Mar 19, 2019
b348546
added clarifications about location of version numbers and semantic v…
mnm678 May 2, 2019
a80ab21
add intermediate root metadata for root metadata format changes
mnm678 May 22, 2019
03f7e59
added details and clarifications
mnm678 Jun 5, 2019
8c4c1a3
minor edits
mnm678 Jun 6, 2019
6de5c5d
fix link
mnm678 Jun 6, 2019
0b71af6
Added detail and reorganized sections
mnm678 Jun 10, 2019
2c3fcd9
clarifications and link to implementation
mnm678 Jul 4, 2019
1375ce5
added clarifications and example about how spec-version updates are h…
mnm678 Jul 5, 2019
156897b
minor edits
mnm678 Jul 5, 2019
0c178cf
Changes to address special cases.
mnm678 Jul 15, 2019
4bb95ee
Added use cases and description of directory structure
mnm678 Jul 22, 2019
87d57c2
clarifications and minor edits
mnm678 Aug 20, 2019
48cc83a
added some description
mnm678 Aug 22, 2019
986b3e3
added clarifications and grammar fixes
mnm678 Aug 26, 2019
f5999be
fix backward compatibility description
mnm678 Aug 27, 2019
3055189
add more rationale
mnm678 Oct 3, 2019
124e82f
add clarifications and security analysis
mnm678 Oct 8, 2019
468c6b8
Formatting changes
mnm678 Oct 10, 2019
2b7e8d7
clarifications to the multiple repositories case
mnm678 Oct 18, 2019
c9912d5
rework intro sections
mnm678 Oct 31, 2019
c1921b7
minor edits and fixes to abstract and rationale
mnm678 Nov 6, 2019
5ba968f
Apply suggestions from code review
mnm678 Jan 3, 2020
30202de
Added clarification based on review.
mnm678 Jan 3, 2020
9790a0c
Apply suggestions from code review
mnm678 Jan 14, 2020
4cee0bd
Added clarifications based on review. Especially:
mnm678 Jan 23, 2020
e927183
Add clarifications, especially:
mnm678 Feb 10, 2020
3f78127
Apply suggestions from code review
mnm678 Jul 9, 2020
cb81016
Update example as TUF is on version 1.0.x
mnm678 Jul 16, 2020
817e993
spec to specification and other minor edits for consistency and accuracy
mnm678 Jul 20, 2020
161db51
update with semantic versioning implementation link
mnm678 Jul 20, 2020
f218b82
add deprecation_timestamp field for targets metadata
mnm678 Jul 20, 2020
94183f9
Apply suggestions from code review
mnm678 Jul 21, 2020
d75e5c9
replace deprecation_timestamp with becomes_obsolete
mnm678 Jul 21, 2020
3fe4e52
additionally add becomes_obsolete to the timestamp metadata
mnm678 Jul 21, 2020
a6b3105
move becomes_obsolete to root
mnm678 Jul 24, 2020
b5d3bd9
Add clarifications from review
mnm678 Aug 6, 2020
b6b04e9
Add TAP number 14 to the version management TAP
mnm678 Aug 7, 2020
c933d87
Merge branch 'master' into tuf-versions
mnm678 Aug 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions candidate-tuf-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,30 @@ the creation of new metadata files in the directory for the phased out version.
In order to allow clients to parse the root metadata chain, root metadata files
shall not be deleted even once a version is deprecated.

A repository may indicate the planned phase out of a major version using an
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joshuagl I added a deprecation field as discussed. A couple of notes:

  • I decided to add the field to targets metadata. I considered root, but changes to root metadata are usually harder to manage (with several offline keys). Also, the targets metadata can be used to indicate deprecation both for top-level metadata and for delegated targets metadata.
  • I'm not a big fan of the name deprecation_timestamp, so am open to any clearer or shorter name suggestions

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not putting this in root seems sensible. Is Targets the best role to include this in? Would the Snapshot make more sense? Or are you trying to avoid having this in metadata which will often be signed by online keys?

Regarding the name, would becomes_obsolete work better? It's not shorter, but may be clearer?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went with targets instead of snapshot/timestamp mostly to allow the field to differ in delegated targets. The only attack that I can think of on this field would be a denial of service (or convincing a client to upgrade early, but it's hard to imagine that being a successful attack), so the online keys shouldn't be too much of a problem. However in this design delegated targets may use a different TUF specification version than the top-level metadata, so having this field for each targets metadata file seems useful. For example an individual delegated targets file could stop supporting version 1.x before the top-level metadata, so this field would allow them to indicate this change to the client.

I like becomes_obsolete, I'll update that in the text.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yes. I forgot about the desire to support different metadata versions in delegated targets.

I was thinking it might make more sense in an earlier role in the client workflow. If we have root, timestamp or snapshot metadata which has expired a client can't know whether that's because the metadata is obsolete, or whether something else happened (because we check the expiration on root, timestamp and snapshot and abort if the expiration has passed long before we ever download targets).

My hope was that this metadata field would

  1. inform clients when a version of the metadata which hasn't expired is due to be deprecated – this use-case appears to be supported by having becomes_obsolete in targets metadata
  2. allow clients to figure out whether metadata that has expired is due to deprecation or something more worrisome – this use-case does not seem to be supported by having becomes_obsolete in targets metadata

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could also add this field to the timestamp metadata to address case 2 (with the caveat that this would not help if root metadata expires). This would also ensure that the client checks this field even if no target files have been updated (when they might not download targets metadata).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still have reservations about this not being in the root metadata – how do clients detect unintentionally expired root metadata (or an attack) vs. obsolete root metadata? Or, phrased differently, how does a client know when updates may be available, just at a different end-point, versus updates being unavailable?

I acknowledge your concerns about including becomes_obsolete in the root metadata being harder to manage. Updating metadata specification versions is a big thing, but should it require a quorum of the root signers and their offline keys? 🤷

The reason I keep belabouring this point is because, to my mind, this is an aspect of TUF's freshness security design principle. The TUF website states that:

a client should be able to recognize that updates may exist that they haven't been able to obtain.

I'd argue that's not possible if the client can't detect the difference between root metadata expiring and root metadata being marked as obsolete.

Copy link
Member

@JustinCappos JustinCappos Jul 22, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've read and thought about this and I can see why we're having an extended discussion on this point. I think this is a hard decision.

If you believe the repository is the arbiter of truth and trust, then keeping it in the root role makes sense. This does effectively let the repository's root role deprecate large swaths of targets files though. This can be good or bad.

If you think that the developer keys (targets metadata files) are what should be trusted, then having a field in targets makes sense. (I would argue for version number instead of timestamp since there isn't a global clock / sync requirement for most of TUF except perhaps to print a warning about outdated timestamp metadata.) This allows parties that delegate make the choice about what versions of metadata are alright. I do feel like this option means that no one will ever use this and that old metadata will be kept around indefinitely, because I just can't see developers worrying about using this flag...

Anyways, this is just my brain dump on the subject...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how do clients detect unintentionally expired root metadata (or an attack) vs. obsolete root metadata?

Root metadata is designed to expire fairly infrequently, so clients would have a long time (potentially a year or more) to notice the becomes_obsolete field in timestamp metadata. However, I agree that updating the specification should be done with the knowledge of the root signers, so maybe including this field in root might be reasonable as it is rarely updated.

If you believe the repository is the arbiter of truth and trust, then keeping it in the root role makes sense. This does effectively let the repository's root role deprecate large swaths of targets files though. This can be good or bad.

I think regardless of whether this field goes in timestamp or root, it also needs to exist in targets metadata for this reason. In this design delegated targets metadata can use a different specification version than the top-level roles, so they need their own way to indicate deprecation. This is especially important when targets metadata is replicated across multiple repositories.

I would argue for version number instead of timestamp since there isn't a global clock / sync requirement for most of TUF except perhaps to print a warning about outdated timestamp metadata.

This may be another argument in favor of putting this field in root. Root metadata is always versioned whereas timestamp metadata is only versioned if consistent snapshots are used.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I would argue for version number instead of timestamp since there isn't a global clock / sync requirement for most of TUF except perhaps to print a warning about outdated timestamp metadata.)

Is that true? The detailed client workflow in the latest spec states:

1.8. Check for a freeze attack. The latest known time should be lower than the expiration timestamp in the trusted root metadata file (version N). If the trusted root metadata file has expired, abort the update cycle, report the potential freeze attack. On the next update cycle, begin at step 0 and version N of the root metadata file.

I'm not sure how checking for a becomes_obsolete date in the metadata is any different from the requirement here to abandon an update if the root metadata file appears to have expired?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about this more, I think that a timestamp might be more useful to clients than a version number as it allows them to make a plan for upgrading, especially in airgapped environments or anywhere else when upgrading might take some planning.

So, per this discussion I will update the TAP to include the becomes_obsolete field in root and targets, and leave its contents as the timestamp for now. This field is optional so if updating root or using a timestamp is an issue, it could be left out.

optional `deprecation_timestamp` field in targets metadata. This field can be
added to targets metadata once a date is set for deprecation of a TUF
specification version by the repository and will include the timestamp after
which the metadata for the current specification version will no longer be
maintained. Inclusion of this field will signal to clients both that they will
mnm678 marked this conversation as resolved.
Show resolved Hide resolved
need to upgrade to the next specification version before the timestamp, and
that there will not be metadata available in the current directory after this
point. Both top-level and delegated targets metadata may use this field to
indicate the point after which the given TUF specification version will no
longer be supported. With the addition of this field, the "signed" portion of
targets metadata will include the following:

```
{ "_type" : "targets",
"spec_version" : SPEC_VERSION,
"version" : VERSION,
"expires" : EXPIRES,
"targets" : TARGETS,
("deprecation_timestamp": DEPRECATION_TIMESTAMP),
("delegations" : DELEGATIONS)
}
```

A repository should generate all TUF metadata, including root metadata, for all
TUF versions that the repository supports. Any update should be reflected across
all of these versions. For clarity, version numbers used for consistent
Expand Down Expand Up @@ -388,6 +412,17 @@ client should maintain functions to parse root files from previous spec
versions. If the client does not support the specification version of a root file, the
client shall terminate the update and report the specification version mismatch.

When a client validates targets metadata, they may check for the
`deprecation_timestamp` field. If this field is present, the client should do
the following:
* If the current time is after the time listed in `deprecation_timestamp`, the
client should report to the user that the update is not available due to a
version mismatch and consider the current targets metadata file invalid. If
this is the top-level targets file, the update should be terminated.
* Otherwise, the client should warn the user that the TUF specification version
they are using will be deprecated at the time indicated by `deprecation_timestamp`
and proceed with the update.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change


## Special Cases

Expand Down