From bd1ad15bb4b6bbc93c9f8841229aee70a188a3b7 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Tue, 26 Jul 2022 13:35:37 -0400 Subject: [PATCH 01/17] [TAP 14] Replace reference to TAP 5 with TAP 13 Signed-off-by: Marina Moore --- tap14.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/tap14.md b/tap14.md index 9d97c300..c4a482cf 100644 --- a/tap14.md +++ b/tap14.md @@ -478,25 +478,25 @@ provided by each repository. Note that different TUF versions may use different hashing algorithms. If this is the case, both hashes should be verified independently. -### TAP 5 +### TAP 13 -A TUF client that supports TAP 5 may download top-level metadata from multiple -sources. However, breaking changes may require that multiple top-level metadata -files use the same TUF specification version. To manage this, a root metadata -file that includes a list of urls for metadata as described in TAP 5 should -only include links to metadata files using the same TUF specification version as -the root metadata file. +A TUF client that supports TAP 13 may download targets metadata from multiple +sources. However, breaking changes may require that all top-level metadata +files use the same TUF specification version. To manage this, a client +configuration file that lists a custom top-level targets metadata file +as described in TAP 13 should only include targets metadata files using the +same TUF specification version as the root metadata file. -The owner of root metadata is responsible for ensuring that all metadata files -linked in the root metadata use the same TUF specification version as the root +The owner of the client configuration is responsible for ensuring that any +custom targets metadata files use the same TUF specification version as the root metadata. If the repository that contains the root metadata supports multiple -TUF specification versions, each root metadata file should list top-level -metadata corresponding with its TUF specification version. +TUF specification versions, the client configuration should list a targets metadata +file that is available in all supported specification versions. Clients should verify that all top-level metadata use the same TUF specification -version as the root metadata. If a metadata file linked in root metadata does -not meet this criteria, it will be considered invalid and the client should -use the next listed metadata file or terminate the update. +version as the root metadata. If a metadata file provided by the TAP 13 configuration +does not meet this criteria, it will be considered invalid and the client should +terminate the update. ### Delegations From b7f539a9c8292ee51b88d46ddcf308aac435beb8 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Tue, 26 Jul 2022 13:53:16 -0400 Subject: [PATCH 02/17] [TAP 14] Add supported-version file Signed-off-by: Marina Moore --- tap14.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/tap14.md b/tap14.md index c4a482cf..ea715715 100644 --- a/tap14.md +++ b/tap14.md @@ -163,6 +163,8 @@ with a directory for each supported TUF specification version. These directories contain metadata that supports the given TUF specification version. Using these directories, a client is able to choose the most recent metadata they support. More details about this directory structure are contained in the [specification](#how-a-repository-updates). +The repository may also maintain a `supported-version` file so that the client +can discover the supported specification versions on the repository. On the client side, this TAP also requires maintenance of multiple versions that support different major TUF specification @@ -178,7 +180,8 @@ version. A specification change may rely on more than one metadata file (for example a change in the signing process would affect all metadata types), so using the same specification version for top-level metadata allows for these large changes to the specification. For information about how this relates to -url pinning and TAP 5, see [Special Cases](#tap-5). However, delegated targets metadata may not be +targets metadta pinning and TAP 13, see [Special Cases](#tap-13). However, +delegated targets metadata may not be managed by the same parties as the top-level metadata. For this reason, this TAP allows clients to use a different TUF specification version for delegated targets by maintaining functions to parse metadata that conforms to different @@ -234,6 +237,7 @@ small changes to existing features. More details about what constitutes a major, minor, or patch change can be found at https://semver.org/. ### Changes to TAPs + In order to manage changes to TUF, TAPs shall be tied to a version of the TUF specification. @@ -245,7 +249,7 @@ has been updated to include the TUF Version field. ## How a repository updates Repositories will add metadata for new TUF specification versions in new -directories. +directories and may maintain a `supported-versions` file. As described in the [Rationale](#rationale), repositories should support multiple TUF specification versions. In order to do so, this TAP proposes a new directory @@ -361,6 +365,20 @@ upgrades from version 1.0.0 to version 2.0.0 may look like: |- 2.0.0 metadata files ``` +Not all TUF repositories have file systems that are able to list all directories +in a folder (the equivalent of the `ls` command). For these repositories (such +as OCI registries or html servers), the repository SHOULD include a +`supported-versions` file in the top of this directory structure that lists +all versions supported by the repository to allow for client discovery. This file +will have the following fields: + +``` +{ "supported_versions" : [VERSION, ...], + +``` + +where `VERSION` is the name of a supported version in the format `version-number.0.0` (i.e. 2.0.0). + ## Changes to TUF clients TUF clients must store the TUF specification versions they support and may add @@ -397,7 +415,8 @@ the client looks for the highest supported version on the repository using the following procedure: * The client determines the latest version available on the repository by -looking for the directory with the largest version number. +looking for the directory with the largest version number, or by parsing the +`supported-versions` file. * If the latest version on the repository is lower than the previous specification version the client used from this repository, the client should report an error and terminate the update. @@ -529,7 +548,9 @@ attacks and changes to the security model that should be discussed. A downgrade attack on the TUF specification version may be possible if an attacker is able to block access to a directory on the repository. This would mean that a client would use metadata from a previous specification version when -performing an update. However, the metadata would still have to be current and +performing an update. Similarly, an attacker on the repository could replace the +`supported-versions` file to remove the most recent specification version. +However, in both of these cases the metadata would still have to be current and properly signed. Clients that have previously used a repository will store the specification From bd6c2a7e75f1e242bdba3cbad28d2b2b04612dcf Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Thu, 4 Aug 2022 15:34:12 -0400 Subject: [PATCH 03/17] [TAP 14] typos and clarifications from code review Signed-off-by: Marina Moore --- tap14.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/tap14.md b/tap14.md index ea715715..b8b8b5b5 100644 --- a/tap14.md +++ b/tap14.md @@ -163,7 +163,7 @@ with a directory for each supported TUF specification version. These directories contain metadata that supports the given TUF specification version. Using these directories, a client is able to choose the most recent metadata they support. More details about this directory structure are contained in the [specification](#how-a-repository-updates). -The repository may also maintain a `supported-version` file so that the client +The repository may also maintain a `supported-versions` file so that the client can discover the supported specification versions on the repository. On the client side, this TAP also requires maintenance of multiple versions that @@ -180,7 +180,7 @@ version. A specification change may rely on more than one metadata file (for example a change in the signing process would affect all metadata types), so using the same specification version for top-level metadata allows for these large changes to the specification. For information about how this relates to -targets metadta pinning and TAP 13, see [Special Cases](#tap-13). However, +targets metadata pinning and TAP 13, see [Special Cases](#tap-13). However, delegated targets metadata may not be managed by the same parties as the top-level metadata. For this reason, this TAP allows clients to use a different TUF specification version for delegated @@ -365,9 +365,9 @@ upgrades from version 1.0.0 to version 2.0.0 may look like: |- 2.0.0 metadata files ``` -Not all TUF repositories have file systems that are able to list all directories +Not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such -as OCI registries or html servers), the repository SHOULD include a +as OCI registries or http servers), the repository SHOULD include a `supported-versions` file in the top of this directory structure that lists all versions supported by the repository to allow for client discovery. This file will have the following fields: @@ -499,8 +499,9 @@ independently. ### TAP 13 -A TUF client that supports TAP 13 may download targets metadata from multiple -sources. However, breaking changes may require that all top-level metadata +A TUF client that supports TAP 13 may download targets metadata that were +uploaded by different parties. +However, breaking changes may require that all top-level metadata files use the same TUF specification version. To manage this, a client configuration file that lists a custom top-level targets metadata file as described in TAP 13 should only include targets metadata files using the From c68087ffab3dbd2175c31d5f43a8ed857d8eedd4 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Thu, 4 Aug 2022 15:38:58 -0400 Subject: [PATCH 04/17] [TAP 14] change directory names 2.0.0 -> 2 Signed-off-by: Marina Moore --- tap14.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/tap14.md b/tap14.md index b8b8b5b5..2dd67dfe 100644 --- a/tap14.md +++ b/tap14.md @@ -255,7 +255,7 @@ As described in the [Rationale](#rationale), repositories should support multipl TUF specification versions. In order to do so, this TAP proposes a new directory structure for repositories. When a repository manager chooses to upgrade to a new major TUF specification version, they create a new directory on the repository named -for the major version (for example 2.0.0). This directory will contain all +for the major version (for example 2). This directory will contain all metadata files for the new specification version, but target files will remain in the parent directory to save space. In this case the metadata files (in directories according to their spec version) can point to target files relative to the parent directory. After creating @@ -270,16 +270,16 @@ version 2.0.0, the repository structure may look like: ``` - Target files -- 1.0.0 +- 1 |- metadata files -- 2.0.0 +- 2 |- metadata files ``` Repository updates to a new minor or patch specification version shall be done by uploading new metadata files in the new format to the proper directory. So if a repository updates from 2.0.0 to 2.1.0, the 2.1.0 metadata would go in the -directory named 2.0.0. Minor and patch version changes are backwards compatible, +directory named 2. Minor and patch version changes are backwards compatible, so clients using version 2.0.0 will still be able to parse metadata written using version 2.1.0. @@ -346,23 +346,23 @@ TUF versions that the repository supports. Any update should be reflected across all of these versions. For clarity, version numbers used for consistent snapshots should be consistent across all supported specification versions so that a client can find the current -metadata files. This means that there may be a file at 1.0.0/3.root.json as well -as 2.0.0/3.root.json. Root metadata files with the same consistent snapshot number must +metadata files. This means that there may be a file at 1/3.root.json as well +as 2/3.root.json. Root metadata files with the same consistent snapshot number must also use the same keys so that a client can find the next root metadata file in whichever specification version they support. For existing TUF clients to continue operation after this TAP is implemented, repositories may store metadata from before TUF 2.0.0 in the top-level -repository (with no directory named 1.0.0). This allows existing clients to +repository (with no directory named 1). This allows existing clients to continue downloading metadata from the repository. So a TUF repository that -upgrades from version 1.0.0 to version 2.0.0 may look like: +upgrades from version 1.x.x to version 2.0.0 may look like: ``` - Targets files -- 1.0.0 metadata files -- 2.0.0 - |- 2.0.0 metadata files +- 1.x.x metadata files +- 2 + |- 2.x.x metadata files ``` Not all TUF repositories have a mechanism that is able to list all directories @@ -377,7 +377,7 @@ will have the following fields: ``` -where `VERSION` is the name of a supported version in the format `version-number.0.0` (i.e. 2.0.0). +where `VERSION` is the name of a supported major version (i.e. 2). ## Changes to TUF clients @@ -437,13 +437,13 @@ Once the supported directory is determined, the client shall attempt the update using the metadata in this directory. For example, if a client has a specification version of 3.5 and a repository has -directories for 2.0.0, 3.0.0, and 4.0.0, the client will report that spec -version 4.x is available, then download metadata from the 3.0.0 directory. This reporting is +directories for 2, 3, and 4, the client will report that spec +version 4.x is available, then download metadata from the 3 directory. This reporting is up to the discretion of an implementer, but it should be used to encourage updating the client to the most recent specification version. Alternatively, if the same client downloads metadata from a repository with -directories 1.0.0 and 2.0.0, the client could download metadata from 2.0.0 using +directories 1 and 2, the client could download metadata from 2 using a 2.x version of the client. If 2.x is not supported by the client, the client will report that it is unable to perform an update. @@ -460,7 +460,7 @@ major version of the root file. So, if the currently trusted root file is named 4.root.json and uses version 1.0.0 and the highest supported version is 3.0.0, the client will look for -5.root.json first in 3.0.0, then 2.0.0, then 1.0.0. If this file is found, the +5.root.json first in 3, then 2, then 1. If this file is found, the client will look for 6.root.json using the same process. To facilitate this, the 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 From 840bbdaef85198e4b80e567b40b92fa592701bec Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Tue, 9 Aug 2022 14:36:56 -0400 Subject: [PATCH 05/17] [TAP 14] minor changes from code review Signed-off-by: Marina Moore --- tap14.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tap14.md b/tap14.md index 2dd67dfe..e8956d3b 100644 --- a/tap14.md +++ b/tap14.md @@ -181,7 +181,7 @@ example a change in the signing process would affect all metadata types), so using the same specification version for top-level metadata allows for these large changes to the specification. For information about how this relates to targets metadata pinning and TAP 13, see [Special Cases](#tap-13). However, -delegated targets metadata may not be +delegated targets metadata might not be managed by the same parties as the top-level metadata. For this reason, this TAP allows clients to use a different TUF specification version for delegated targets by maintaining functions to parse metadata that conforms to different @@ -249,7 +249,7 @@ has been updated to include the TUF Version field. ## How a repository updates Repositories will add metadata for new TUF specification versions in new -directories and may maintain a `supported-versions` file. +directories and SHOULD maintain a `supported-versions` file. As described in the [Rationale](#rationale), repositories should support multiple TUF specification versions. In order to do so, this TAP proposes a new directory @@ -439,7 +439,7 @@ using the metadata in this directory. For example, if a client has a specification version of 3.5 and a repository has directories for 2, 3, and 4, the client will report that spec version 4.x is available, then download metadata from the 3 directory. This reporting is -up to the discretion of an implementer, but it should be used to encourage +up to the discretion of each application, but it should be used to encourage updating the client to the most recent specification version. Alternatively, if the same client downloads metadata from a repository with From a7c0cfe0a89f99f3ef014c821b277406d133b8f4 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Thu, 15 Sep 2022 10:35:43 -0400 Subject: [PATCH 06/17] clarify backwards compatibility and type of 'version' Signed-off-by: Marina Moore --- tap14.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tap14.md b/tap14.md index e8956d3b..9cae33ae 100644 --- a/tap14.md +++ b/tap14.md @@ -377,7 +377,9 @@ will have the following fields: ``` -where `VERSION` is the name of a supported major version (i.e. 2). +where `VERSION` is the integer name of a supported major version (i.e. 2). +For backwards compatability, version 1 should be assumed to be in the top-level +repository with no directory named 1. ## Changes to TUF clients From 0f137d970161f7abd7f08d8998ad3f9454f6d89e Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Wed, 21 Sep 2022 17:35:26 -0400 Subject: [PATCH 07/17] [TAP 14] change fields in supported-versions.json Signed-off-by: Marina Moore --- tap14.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/tap14.md b/tap14.md index 9cae33ae..3fc1a194 100644 --- a/tap14.md +++ b/tap14.md @@ -248,8 +248,10 @@ has been updated to include the TUF Version field. ## How a repository updates -Repositories will add metadata for new TUF specification versions in new -directories and SHOULD maintain a `supported-versions` file. +Repositories will add two things. They MUST put metadata for new TUF +specification versions in new +directories. In addition, repositories SHOULD maintain a `supported-versions` file +to indicate which specification versions are supported. As described in the [Rationale](#rationale), repositories should support multiple TUF specification versions. In order to do so, this TAP proposes a new directory @@ -368,16 +370,23 @@ upgrades from version 1.x.x to version 2.0.0 may look like: Not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such as OCI registries or http servers), the repository SHOULD include a -`supported-versions` file in the top of this directory structure that lists +`supported-versions.json` file in the top of this directory structure that lists all versions supported by the repository to allow for client discovery. This file -will have the following fields: +will be signed by a threshold of root keys, and the `signed` portion will have +the following fields: ``` -{ "supported_versions" : [VERSION, ...], +{ "supported_versions" : [ + { MAJOR_VERSION: FOLDER_NAME}, + ... + ] +} ``` -where `VERSION` is the integer name of a supported major version (i.e. 2). +where `MAJOR_VERSION` is the integer representing a supported major version (i.e. 2) +and `FOLDER_NAME` is the integer representing the folder containing metadata for +this supported major version. In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`. For backwards compatability, version 1 should be assumed to be in the top-level repository with no directory named 1. From 77e9455284b849e7bcd7334787d43cb8ebe45323 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Wed, 21 Sep 2022 18:24:17 -0400 Subject: [PATCH 08/17] [TAP 14] supported-versions -> supported-versions.json Signed-off-by: Marina Moore --- tap14.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tap14.md b/tap14.md index 3fc1a194..b68d6e9e 100644 --- a/tap14.md +++ b/tap14.md @@ -163,7 +163,7 @@ with a directory for each supported TUF specification version. These directories contain metadata that supports the given TUF specification version. Using these directories, a client is able to choose the most recent metadata they support. More details about this directory structure are contained in the [specification](#how-a-repository-updates). -The repository may also maintain a `supported-versions` file so that the client +The repository may also maintain a `supported-versions.json` file so that the client can discover the supported specification versions on the repository. On the client side, this TAP also requires maintenance of multiple versions that @@ -250,7 +250,7 @@ has been updated to include the TUF Version field. Repositories will add two things. They MUST put metadata for new TUF specification versions in new -directories. In addition, repositories SHOULD maintain a `supported-versions` file +directories. In addition, repositories SHOULD maintain a `supported-versions.json` file to indicate which specification versions are supported. As described in the [Rationale](#rationale), repositories should support multiple @@ -385,7 +385,7 @@ the following fields: ``` where `MAJOR_VERSION` is the integer representing a supported major version (i.e. 2) -and `FOLDER_NAME` is the integer representing the folder containing metadata for +and `FOLDER_NAME` is the string representing the folder containing metadata for this supported major version. In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`. For backwards compatability, version 1 should be assumed to be in the top-level repository with no directory named 1. @@ -427,7 +427,7 @@ following procedure: * The client determines the latest version available on the repository by looking for the directory with the largest version number, or by parsing the -`supported-versions` file. +`supported-versions.json` file. * If the latest version on the repository is lower than the previous specification version the client used from this repository, the client should report an error and terminate the update. @@ -561,7 +561,7 @@ A downgrade attack on the TUF specification version may be possible if an attacker is able to block access to a directory on the repository. This would mean that a client would use metadata from a previous specification version when performing an update. Similarly, an attacker on the repository could replace the -`supported-versions` file to remove the most recent specification version. +`supported-versions.json` file to remove the most recent specification version. However, in both of these cases the metadata would still have to be current and properly signed. From eb32ea55bd85d2c694609b5b0e21099d7a4c3efa Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Thu, 22 Sep 2022 16:10:14 -0400 Subject: [PATCH 09/17] [TAP 14] updated format for supported-versions.json Signed-off-by: Marina Moore --- tap14.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/tap14.md b/tap14.md index b68d6e9e..3f1173a4 100644 --- a/tap14.md +++ b/tap14.md @@ -377,16 +377,19 @@ the following fields: ``` { "supported_versions" : [ - { MAJOR_VERSION: FOLDER_NAME}, + { "version": MAJOR_VERSION, + "path": FOLDER_NAME}, ... ] } ``` -where `MAJOR_VERSION` is the integer representing a supported major version (i.e. 2) +where `MAJOR_VERSION` is the integer representing a supported major version and `FOLDER_NAME` is the string representing the folder containing metadata for -this supported major version. In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`. +this supported major version (e.g. { "version": 2, "path": "2" }). +`FOLDER_NAME` MUST NOT contain any subdirectories. +In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`. For backwards compatability, version 1 should be assumed to be in the top-level repository with no directory named 1. From 3269d8b9fae2b2a4cabe7f1e0ca67741701c52f9 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Mon, 26 Sep 2022 12:06:36 -0400 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: Trishank Karthik Kuppusamy Signed-off-by: Marina Moore --- tap14.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tap14.md b/tap14.md index 3f1173a4..6105e49e 100644 --- a/tap14.md +++ b/tap14.md @@ -357,17 +357,17 @@ For existing TUF clients to continue operation after this TAP is implemented, repositories may store metadata from before TUF 2.0.0 in the top-level repository (with no directory named 1). This allows existing clients to continue downloading metadata from the repository. So a TUF repository that -upgrades from version 1.x.x to version 2.0.0 may look like: +upgrades from version 1.x.y to version 2.0.0 may look like: ``` - Targets files -- 1.x.x metadata files +- 1.x.y metadata files - 2 - |- 2.x.x metadata files + |- 2.x.y metadata files ``` -Not all TUF repositories have a mechanism that is able to list all directories +Not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such as OCI registries or http servers), the repository SHOULD include a `supported-versions.json` file in the top of this directory structure that lists From 0b27e8849c1c4bb5095ba16d68e8b1db5ed2c7c5 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Fri, 30 Sep 2022 13:50:51 -0400 Subject: [PATCH 11/17] move supported versions into root metadata Signed-off-by: Marina Moore --- tap14.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/tap14.md b/tap14.md index 6105e49e..e867f805 100644 --- a/tap14.md +++ b/tap14.md @@ -163,7 +163,7 @@ with a directory for each supported TUF specification version. These directories contain metadata that supports the given TUF specification version. Using these directories, a client is able to choose the most recent metadata they support. More details about this directory structure are contained in the [specification](#how-a-repository-updates). -The repository may also maintain a `supported-versions.json` file so that the client +This TAP will also add a `supported-versions` field to root metadata so that the client can discover the supported specification versions on the repository. On the client side, this TAP also requires maintenance of multiple versions that @@ -250,7 +250,7 @@ has been updated to include the TUF Version field. Repositories will add two things. They MUST put metadata for new TUF specification versions in new -directories. In addition, repositories SHOULD maintain a `supported-versions.json` file +directories. In addition, root metadata on a repository SHOULD add a `supported-versions` field to indicate which specification versions are supported. As described in the [Rationale](#rationale), repositories should support multiple @@ -369,14 +369,15 @@ upgrades from version 1.x.y to version 2.0.0 may look like: Not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such -as OCI registries or http servers), the repository SHOULD include a -`supported-versions.json` file in the top of this directory structure that lists -all versions supported by the repository to allow for client discovery. This file -will be signed by a threshold of root keys, and the `signed` portion will have -the following fields: +as OCI registries or http servers), as well as to prevent specification version +freeze attacks, root metadata SHOULD include a `supported-versions` field that lists +all versions supported by the repository to allow for client discovery. As it is +included in root metadata, this field will be signed by a threshold of root keys, +and will contain the following fields: ``` -{ "supported_versions" : [ +{ ..., + "supported_versions" : [ { "version": MAJOR_VERSION, "path": FOLDER_NAME}, ... @@ -430,7 +431,7 @@ following procedure: * The client determines the latest version available on the repository by looking for the directory with the largest version number, or by parsing the -`supported-versions.json` file. +`supported-versions` field in root metadata. * If the latest version on the repository is lower than the previous specification version the client used from this repository, the client should report an error and terminate the update. @@ -563,10 +564,9 @@ attacks and changes to the security model that should be discussed. A downgrade attack on the TUF specification version may be possible if an attacker is able to block access to a directory on the repository. This would mean that a client would use metadata from a previous specification version when -performing an update. Similarly, an attacker on the repository could replace the -`supported-versions.json` file to remove the most recent specification version. -However, in both of these cases the metadata would still have to be current and -properly signed. +performing an update. +However, a client would be able to detect this attack using the `supported-versions` +field listed in root metadata and signed with root keys. Clients that have previously used a repository will store the specification version used to communicate with that repository, so a downgrade attack will From 8abc271d088fba11a3c1fd21b3cd7150b50a94be Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 6 Oct 2022 15:20:51 +0200 Subject: [PATCH 12/17] TAP 14: Fix new field name inconsistency Consistently use "supported_versions" (with underscore) as name for newly added field. Signed-off-by: Lukas Puehringer --- tap14.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tap14.md b/tap14.md index e867f805..79a6c362 100644 --- a/tap14.md +++ b/tap14.md @@ -163,7 +163,7 @@ with a directory for each supported TUF specification version. These directories contain metadata that supports the given TUF specification version. Using these directories, a client is able to choose the most recent metadata they support. More details about this directory structure are contained in the [specification](#how-a-repository-updates). -This TAP will also add a `supported-versions` field to root metadata so that the client +This TAP will also add a `supported_versions` field to root metadata so that the client can discover the supported specification versions on the repository. On the client side, this TAP also requires maintenance of multiple versions that @@ -250,7 +250,7 @@ has been updated to include the TUF Version field. Repositories will add two things. They MUST put metadata for new TUF specification versions in new -directories. In addition, root metadata on a repository SHOULD add a `supported-versions` field +directories. In addition, root metadata on a repository SHOULD add a `supported_versions` field to indicate which specification versions are supported. As described in the [Rationale](#rationale), repositories should support multiple @@ -370,7 +370,7 @@ upgrades from version 1.x.y to version 2.0.0 may look like: Not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such as OCI registries or http servers), as well as to prevent specification version -freeze attacks, root metadata SHOULD include a `supported-versions` field that lists +freeze attacks, root metadata SHOULD include a `supported_versions` field that lists all versions supported by the repository to allow for client discovery. As it is included in root metadata, this field will be signed by a threshold of root keys, and will contain the following fields: @@ -431,7 +431,7 @@ following procedure: * The client determines the latest version available on the repository by looking for the directory with the largest version number, or by parsing the -`supported-versions` field in root metadata. +`supported_versions` field in root metadata. * If the latest version on the repository is lower than the previous specification version the client used from this repository, the client should report an error and terminate the update. @@ -565,7 +565,7 @@ A downgrade attack on the TUF specification version may be possible if an attacker is able to block access to a directory on the repository. This would mean that a client would use metadata from a previous specification version when performing an update. -However, a client would be able to detect this attack using the `supported-versions` +However, a client would be able to detect this attack using the `supported_versions` field listed in root metadata and signed with root keys. Clients that have previously used a repository will store the specification From 6cee55c55b3640a0b713cefc1371ea16462c1312 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 6 Oct 2022 15:36:14 +0200 Subject: [PATCH 13/17] TAP 14: Fix update metadata parsing order In a real TUF client update timestamp parsing happens before snapshot parsing. Signed-off-by: Lukas Puehringer --- tap14.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tap14.md b/tap14.md index 79a6c362..dad2773a 100644 --- a/tap14.md +++ b/tap14.md @@ -190,7 +190,7 @@ metadata files while allowing flexibility in how repositories and delegations are managed. For example, during the course of an update a client could use 4.0.0_parse_root, -4.0.0_parse_snapshot, 4.0.0_parse_timestamp, 4.0.0_parse_targets, +4.0.0_parse_timestamp, 4.0.0_parse_snapshot, 4.0.0_parse_targets, 4.0.0_parse_delegation, and 3.0.0_parse_delegation. From b20114a710751e6b990d5f1ecf0d56cf28ece79d Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 6 Oct 2022 15:39:14 +0200 Subject: [PATCH 14/17] TAP 14: Rm bad example of backwards compatible TAP TAP 10 is wrongly used as example for a backwards compatible TAP, at least according to the "Backwards Compatibility" section in TAP 10: https://github.com/theupdateframework/taps/blob/master/tap10.md#backwards-compatibility Signed-off-by: Lukas Puehringer --- tap14.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tap14.md b/tap14.md index dad2773a..706145d0 100644 --- a/tap14.md +++ b/tap14.md @@ -225,7 +225,7 @@ and so clients and repositories need to use code that supports the same major version when performing an update in order to maintain security and functionality. If the change adds a new feature that is backwards compatible, for example in -TAP 4 and TAP 10, it should be part of a new minor version. These TAPs add +TAP 4, it should be part of a new minor version. These TAPs add additional features to TUF, but clients that do not have these features will still be able to securely and reliably perform updates from repositories that support the TAPs. There may be minor differences as to which updates a client From 7907b91241f4e54e81e0e32f2f9e57b15ad0dac4 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 6 Oct 2022 16:04:20 +0200 Subject: [PATCH 15/17] TAP 14: Clarify "expires" vs. "becomes_obsolete" Signed-off-by: Lukas Puehringer --- tap14.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tap14.md b/tap14.md index 706145d0..b0b07ad0 100644 --- a/tap14.md +++ b/tap14.md @@ -303,9 +303,9 @@ maintained. Inclusion of this field will signal to clients both that they will 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. The client can check the `becomes_obsolete` field in root metadata -before checking the metadata expiration. This allows them to differentiate -between metadata that is expired due to deprecation and metadata that is expired -due to an attack. Delegated targets may include this field independent of +before checking the metadata expiration. This allows them to differentiate between metadata +that is expired due to intended deprecation, and metadata that is expired, e.g. because +an attacker blocked the update. Delegated targets may include this field independent of top-level metadata to indicate when the metadata they are responsible for will no longer support a given TUF specification version. With the addition of this field, the "signed" portion of targets metadata will include the following: From 966a56d89b21599f279581bcece64dfe07a5d8fc Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Thu, 6 Oct 2022 16:51:43 +0200 Subject: [PATCH 16/17] TAP 14: Clarify how the name convention can change Signed-off-by: Lukas Puehringer --- tap14.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tap14.md b/tap14.md index b0b07ad0..d8e94c89 100644 --- a/tap14.md +++ b/tap14.md @@ -478,7 +478,9 @@ So, if the currently trusted root file is named 4.root.json and uses version 5.root.json first in 3, then 2, then 1. If this file is found, the client will look for 6.root.json using the same process. To facilitate this, the 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 +versions. Note that the library that supports a given spec version may also use +a different naming convention than VERSION.root.json to find the root metadata. +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 root and targets metadata, they may check for the From b7c0d9d7a056fb07db62e07326b33e5046c9ed18 Mon Sep 17 00:00:00 2001 From: Marina Moore Date: Fri, 7 Oct 2022 15:16:55 -0400 Subject: [PATCH 17/17] Simplify root update for TAP 14 Signed-off-by: Marina Moore --- tap14.md | 109 ++++++++++++++++++++++--------------------------------- 1 file changed, 43 insertions(+), 66 deletions(-) diff --git a/tap14.md b/tap14.md index d8e94c89..eefc9529 100644 --- a/tap14.md +++ b/tap14.md @@ -1,7 +1,7 @@ * TAP: 14 * Title: Managing TUF Versions * Version: 1 -* Last-Modified: 07-August-2020 +* Last-Modified: 07-October-2022 * Author: Marina Moore, Justin Cappos * Status: Draft * Content-Type: text/markdown @@ -189,9 +189,9 @@ specification versions. This compromise allows TUF specification changes to affe metadata files while allowing flexibility in how repositories and delegations are managed. -For example, during the course of an update a client could use 4.0.0_parse_root, -4.0.0_parse_timestamp, 4.0.0_parse_snapshot, 4.0.0_parse_targets, -4.0.0_parse_delegation, and 3.0.0_parse_delegation. +For example, during the course of an update a client could use `4.0.0_parse_root`, +`4.0.0_parse_snapshot`, `4.0.0_parse_timestamp`, `4.0.0_parse_targets`, +`4.0.0_parse_delegation`, and `3.0.0_parse_delegation`. # Specification @@ -250,7 +250,7 @@ has been updated to include the TUF Version field. Repositories will add two things. They MUST put metadata for new TUF specification versions in new -directories. In addition, root metadata on a repository SHOULD add a `supported_versions` field +directories. In addition, root metadata on a repository MUST add a `supported_versions` field to indicate which specification versions are supported. As described in the [Rationale](#rationale), repositories should support multiple @@ -265,7 +265,7 @@ the directory, the repository creates and signs root, snapshot, timestamp, and top-level targets metadata using the new TUF specification version and places these metadata files in the directory. The root file should be signed by both the new root key and the current root key (the root key from the most recent metadata in -the previous major specification version). Clients will now be able to use the new +the previous major specification version). The new supported version number, and information about the new root metadata will then be added to `supported-versions` in all previously supported specification versions. Clients will now be able to use the new metadata files once their TUF specification versions are also updated. After an update to version 2.0.0, the repository structure may look like: @@ -343,16 +343,6 @@ And the "signed" portion of root will include: where `BECOMES_OBSOLETE` is a timestamp. -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 -snapshots should be consistent across all -supported specification versions so that a client can find the current -metadata files. This means that there may be a file at 1/3.root.json as well -as 2/3.root.json. Root metadata files with the same consistent snapshot number must -also use the same keys so that a client can find the next root metadata file in whichever -specification version they support. - For existing TUF clients to continue operation after this TAP is implemented, repositories may store metadata from before TUF 2.0.0 in the top-level repository (with no directory named 1). This allows existing clients to @@ -367,19 +357,31 @@ upgrades from version 1.x.y to version 2.0.0 may look like: |- 2.x.y metadata files ``` -Not all TUF repositories have a mechanism that is able to list all directories +In order to fascilitate the upgrade to a new specification version, root metadata for all supported spec versions MUST add a `supported_versions` field before upgrading to spec version 2.0.0. +This field will serve two purpose. + + +First, not all TUF repositories have a mechanism that is able to list all directories in a folder (the equivalent of the `ls` command). For these repositories (such as OCI registries or http servers), as well as to prevent specification version -freeze attacks, root metadata SHOULD include a `supported_versions` field that lists -all versions supported by the repository to allow for client discovery. As it is -included in root metadata, this field will be signed by a threshold of root keys, -and will contain the following fields: +freeze attacks, the `supported_versions` field will lists +all versions supported by the repository to allow for client discovery. + +Second, the root metadata format or versioning scheme may change between major specification versions. +The `supported_versions` field will contain the filename and a secure hash of the first root metadata file that should be used in the new specification version. + +As it is +included in root metadata, the contents of `supported_versions` will be signed by a threshold of root keys, securing against a specification version rollback, and signing the new trusted root metadata. +This field will contain the following: ``` { ..., "supported_versions" : [ { "version": MAJOR_VERSION, - "path": FOLDER_NAME}, + "path": FOLDER_NAME, + "root-filename": ROOT_FILENAME, + "root-digest": ROOT_DIGEST + }, ... ] } @@ -392,7 +394,11 @@ this supported major version (e.g. { "version": 2, "path": "2" }). `FOLDER_NAME` MUST NOT contain any subdirectories. In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`. For backwards compatability, version 1 should be assumed to be in the top-level -repository with no directory named 1. +repository with no directory named 1. `ROOT_FILENAME` is the name of the root metadata file in the new specification version. `ROOT_DIGEST` is the digest of the new root metadata file. + +A repository should generate all TUF metadata, including root metadata, for all +TUF versions that the repository supports. Any update to TUF targets or delegations should be reflected across +all of these versions. ## Changes to TUF clients @@ -422,7 +428,7 @@ remove the higher version and force the client to use a lower versioned, potentially less secure specification version. -## Changes to the update process +### Changes to the update process When a TUF client downloads metadata from a repository, the client must determine which specification version to use for the download. To do this, @@ -430,26 +436,28 @@ the client looks for the highest supported version on the repository using the following procedure: * The client determines the latest version available on the repository by -looking for the directory with the largest version number, or by parsing the -`supported_versions` field in root metadata. -* If the latest version on the repository is lower than the previous +parsing the `supported_versions` field in the currently trusted root metadata. +* The client determines the specification version to use using the following: + * If the latest version on the repository is lower than the previous specification version the client used from this repository, the client should report an error and terminate the update. -* If the latest version on the repository is equal to that of the client, it -will use this directory to download metadata. -* If the latest version pre-dates the client specification version, it may call functions + * If the latest version on the repository is equal to that of the client, it +will use this version to download metadata. + * If the latest version pre-dates the client specification version, it may call functions from a previous client version to download the metadata. The client may support as many or as few versions as desired for the application. If the previous version is not available, the client shall report that an update can not be performed due to an old specification version on the repository. -* If the latest version on the repository is higher than the client spec + * If the latest version on the repository is higher than the client spec version, the client should report to the user that it is not using the most up to date version, and then perform the update with the directory that corresponds with the latest client specification version, if available. If no such directory exists, the client terminates the update. +* If the client will be using a higher specification version than on their previous update, they will update their trusted root metadata by downloading the metadata available in the new specification version's directory at the root metadata location specified in the currently trusted root metadata. The client will verify that the hash of this file matches the digest listed in the current root metadata. If so, the client will set their trusted root metadata to the downloaded file. -Once the supported directory is determined, the client shall attempt the update -using the metadata in this directory. +Once the supported directory is determined and root metadata is updated, the client shall attempt the update +using the metadata in this directory. Every time the trusted root metadata +file is updated, the client should perform this check to determine the specification version to use going forward. For example, if a client has a specification version of 3.5 and a repository has directories for 2, 3, and 4, the client will report that spec @@ -462,27 +470,6 @@ directories 1 and 2, the client could download metadata from 2 using a 2.x version of the client. If 2.x is not supported by the client, the client will report that it is unable to perform an update. -Once the supported directory is determined, the client must validate root -metadata from this directory. If the currently trusted root file saved on the -client uses a specification version other than the supported version, the client will -look for the next root file. The next root file may have been generated using -the supported version, or it may have been generated using a previous TUF -version. The client will look for the root file first in the supported version, -then move to the previous versions until the next root file is found, or until -the currently trusted root file's version is reached. All root files must be -verified using the major version of the TUF client that corresponds with the -major version of the root file. - -So, if the currently trusted root file is named 4.root.json and uses version -1.0.0 and the highest supported version is 3.0.0, the client will look for -5.root.json first in 3, then 2, then 1. If this file is found, the -client will look for 6.root.json using the same process. To facilitate this, the -client should maintain functions to parse root files from previous spec -versions. Note that the library that supports a given spec version may also use -a different naming convention than VERSION.root.json to find the root metadata. -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 root and targets metadata, they may check for the `becomes_obsolete` field. If this field is present, the client should do the following: @@ -547,14 +534,6 @@ version (found using the same procedure as described in compatible specification version between the client and delegation, the client should report this and terminate the update. -### Updating Trusted Root Metadata - -To allow for future updates after a major version change, the client must update -its trusted root metadata to one that complies with the new specification -version. To do so, the client first downloads and verifies the current version -root metadata file, which then must be stored as the trusted root metadata. In -future updates, the client will start from the trusted root metadata to find the -next available update. # Security Analysis @@ -584,10 +563,8 @@ should be revoked or allowed to expire). In addition, clients should be upgraded to no longer support a vulnerable specification version. ## Root Key Rotation -The TUF version upgrade system described in this TAP uses the root key rotation -mechanism to ensure that the client only uses valid TUF metadata. The first time -a new TUF version is used by the client, it checks the repository's root -metadata in the new version's format. If the root metadata is not signed by the +The TUF version upgrade system described in this TAP uses the previous trusted root metadata to sign the root metadata in future specification versions. The first time +a new TUF version is used by the client, it checks the new root metadata against the hash listed in the root metadata of the previously used specification version. If the root metadata is not signed by the previous trusted root key, the update does not proceed, and the client halts the update. In this way, updates to the repository's TUF version do not impact the security of an update.