TAP for adding a Specification Version to root.json

[David Lawrence]

TAP: <to be assigned>
Title: Include Specification Version in root.json
Version: 1
Last-Modified: 05-Oct-2016
Author: David Lawrence
Status: Draft
Created: <to be assigned with TAP # per TAP #1>
TUF-Version: 1.0
Post-History: 05-Oct-2016

Abstract

Tap <to be assigned> adds a requirement that the version of the specification against which the TUF repository should be assessed for validity be included in the root.json of the repository.

Motivation

As the TUF specification evolves there are likely to be breaking changes, for example, commit 5d2c8fdc7658a9f7648c38b0c79c0aa09d234fe2 in github.com/theupdateframework/tuf removes the "Private" field, which would break key ID calculations. Adding the specification version a repository is operating under allows clients to determine and message to users whether they are compatible, rather than breaking in undefined ways.

Rationale

TUF clients would enjoy greater stability, consistency, and interoperability as the TUF spec evolves.

Specification

This TAP proposes adding a new json field named "specification_version" that contains a string value indicating the specification version in use. The field would be added to the "Signed" section of the root.json file.

{ "_type" : "Root",
"specification_version" : "1.0", // new field
"version" : VERSION,
"expires" : EXPIRES,
, ... },
ROLE : {
"keyids" : [ KEYID, ... ] ,
, ... }
}

The use of a string allows for the inclusion of arbitrary additional versioning markers commonly in use such as "alpha", "beta", and "RC". There is an expectation, based on changes that have already been made to the specification, that a client will reliably be able to define that it works in all versions < X with a single implementation variant, which is the sole strong argument for using a numerical data type. Instead it is expected that clients will need to map the specification version to a particular set of behaviour, using a strategy pattern approach, the alternative being code littered with logic branches that fork the behaviour based on the specification version.

Security Analysis

The addition of a "specification_version" field to the root.json increases security by increasing a client's ability to determine the compatibility of its implementation against the structure of the repository it is attempting to process. This can allow it to fail in a well defined way when it recognizes it does not support the spec version in use by the repository.

Backwards Compatibility

The addition of the "specification_version" field is compatible with all existing consumers. However, clients that do not support it and are used to sign and publish a new root file are at risk to strip the field from the root.json. This will happen in at least notary and go-tuf due to their use of concrete types with defined fields to parse retrieved JSON data.

Copyright

This document has been placed in the public domain.

[Vladimir Diaz]

Thanks for submitting a TAP for this feature.  I personally think it's a good idea to have a way of indicating the version of the specification used by a repository.

Thanks,

VLAD

--
vladimi...@gmail.com
PGP fingerprint = ACCF 9DCA 73B9 862F 93C5  6608 63F8 90AA 1D25 3935
--

[David Lawrence]

I just realized there was a typo in the specification section. "that a client will reliably be able to define that it works in all versions < X” should have been "that a client will _not_ reliably be able to define that it works in all versions < X”

[Vladimir Diaz]

Hi David,

May we suggest one change to the TAP?

Correct me if I'm wrong, but including the specification number in root.json implies that all metadata on the repository complies with a particular version of the specification.  However, would this be the case, in practice, for delegated roles?  We think that only including the specification version number in root.json would be a problem for delegated roles that are less often updated.  Compared to most of the other top-level roles, delegated roles are expected to be signed with "offline" (not available on the server) keys.  As the TAP stands, it is possible that a delegated metadata available on the repository is written according to specification version 1.0, while the top-level roles are written according to 2.0 of the specification.

One may overcome this limitation by making sure that delegated roles are updated to follow the new specification format.  Unfortunately, this would be a usability problem for these roles.  For example, delegated roles on a community repository may be managed by external developers that might be unwilling to resign/update their metadata.

Thanks,

Vlad

P.S. We have a reference implementation of the TAP available here: https://github.com/theupdateframework/tuf/tree/spec_version_in_metadata.  Note that the implementation includes the specification version in ALL metadata.

--
vladimi...@gmail.com
PGP fingerprint = ACCF 9DCA 73B9 862F 93C5  6608 63F8 90AA 1D25 3935
--

[David Lawrence]

Hey Vlad,

I thought about doing it per file originally and my biggest concern with that is it prevents deprecation of old versions in the code. A client would hopefully be able to state “supports >= vX” but if the delegations are allowed to lag further behind, it becomes very difficult for a client to do that and guarantee it will work reliably. Overall, it’s messy to allow drift in versions within a single repo so I’m not a fan, however...

If your suggestion is added, would it be reasonable to require a maximum drift, in which the oldest version considered valid for any role can be no more than X versions behind the root? I would suggest the maximum drift should be a static constant defined in the spec, not something left to the individual implementer, otherwise it doesn’t solve the problem.

Additionally, if we add your suggestion, I think it would make sense to implement some kind of version “inheritance” that follows the trust chain, i.e. if no version is defined, the role is considered to have the same version as the parent (targets, timestamp, and snapshot would inherit the root version, delegations would inherit the parent version). Also I think it would make sense to require no role can have a version _higher_ than the root.

What are your thoughts?

David

[Justin Cappos]

I don't think there is anything wrong with a client failing to parse old metadata (or warning about this).  How about if we explicitly deprecate old versions as we release new versions of the TUF spec?

I'm in favor of explicit markings on each file.  In most uses of TUF, the targets metadata will be done in a very distributed fashion and so is likely to have a smattering of versions.  I'd rather not over think this and make implicit information about version information be propagated.  I could imagine cases where this would cause a file to be unintentionally parsed in a way that the original signer did not intend...

Justin  

[David Lawrence]

Clients that can’t parse the same subset of metadata may disagree on the content of the TUF repo, that seems like something that might be open to abuse based on prioritization schemes of delegations.

[Justin Cappos]

Yes, good point.  This would happen if a client just fails over silently to the next file.  I think we would want to require that clients parse the same files or error out if they do not understand them.

Justin

[Vladimir Diaz]

Hello,

We added a draft of TAP 6 (Include specification version in metadata) to the TAPs GitHub repository.  If you wish to provide feedback, please do so on the pull request itself.

https://github.com/theupdateframework/taps/pull/18/files#diff-3a01a32dbb20beb6b81ab11fbd5185d4

Thanks,

Vlad

--
vladimi...@gmail.com
PGP fingerprint = ACCF 9DCA 73B9 862F 93C5  6608 63F8 90AA 1D25 3935
--