Skip to content

Commit b6599b9

Browse files
joshuagljoshuagl
authored
Merge pull request #118 from theupdateframework/tap13
TAP13 draft
2 parents 0de18f1 + 6d480ab commit b6599b9

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515

1616
* [TAP 8: Key rotation and explicit self-revocation](tap8.md)
1717
* [TAP 12: Improving keyid flexibility](tap12.md)
18+
* [TAP 13: User Selection of the Top-Level Target Files Through Mapping Metadata](tap13.md)
1819
* [TAP 14: Managing TUF Versions](tap14.md)
1920
* [TAP 15: Succinct hashed bin delegations](tap15.md)
2021
* [TAP 16: Snapshot Merkle Trees](tap16.md)

‎tap13.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
* TAP: 13
2+
* Title: User Selection of the Top-Level Target Files Through Mapping Metadata
3+
* Version: 1
4+
* Last-Modified: 02-Nov-2021
5+
* Author: Justin Cappos, Joshua Lock, Marina Moore, Lukas Pühringer
6+
* Status: Draft
7+
* Content-Type: text/markdown
8+
* Requires: TAP 4
9+
* Created: 29-May-2020
10+
11+
# Abstract
12+
13+
This TAP discusses a means by which different users of the same repository
14+
may elect to use different, repository-hosted, top-level targets metadata. This
15+
effectively enables different namespaces to exist on a repository which a client
16+
may choose to trust -- or not -- in a granular fashion, and also provides
17+
additional resilience to attack in the case that the root keys on the
18+
repository are compromised.
19+
20+
21+
22+
# Motivation
23+
24+
Currently if a user trusts a TUF repository, a compromise of the targets role
25+
for that repository enables an attacker to install arbitrary malicious software.
26+
The targets role on the repository is responsible for delegating to the correct
27+
key for each delegated targets, and so may also arbitrarily replace these keys.
28+
A third party that controls
29+
a delegated targets role gives their keys to the delegating role on the
30+
repository, then has to trust that the repository will correctly list the
31+
trusted keys for their role. In some cases, the user may wish to reduce trust
32+
in the repository by maintaining control of key distribution.
33+
34+
For users of some public repositories, the repository is considered an untrusted
35+
distribution mechanism, and should not be trusted with this key distribution.
36+
For these repositories, the owner of a delegated targets role needs a mechanism
37+
to ensure that their users can define and pin keys.
38+
39+
To allow for safer use of these untrusted repositories, we propose adding
40+
namespaces to TUF repositories which enable explicit trust decisions. In This
41+
mode, if Alice and Bob both use repository X and ask for package foo, they may
42+
get different results based on their trusted namespaces.
43+
In summary; this proposal enables clients to restrict the targets they consume
44+
to filtered views of the repository.
45+
46+
These different views could be defined by either different users on the
47+
repository, made available by the repository administrator, or be created by
48+
some other third party. Some likely uses include:
49+
* **Limiting packages on a repository to those that have been signed by their
50+
developer.** For example, in the proposed
51+
[PyPI Maximum Security Model](https://www.python.org/dev/peps/pep-0480/),
52+
packages that are only signed by the repository are listed under the 'unclaimed'
53+
targets role, while packages that are signed by developers are delegated
54+
from the 'claimed' targets role. A user may wish to restrict packages to those
55+
that have been end-to-end signed, and so only use packages delegated from
56+
'claimed'.
57+
* **Curating a list of verified packages.** A company may curate a subset of
58+
packages available on a container registry that have been validated for use
59+
by their customers. This curated list may include packages that the company
60+
signs, as well as trusted third-party dependencies. They may then
61+
distribute this curated list to users, who want to ensure that only
62+
validated packages are installed.
63+
64+
There are several reasons why it may be important to let Alice and Bob's view of
65+
the repository differ.
66+
67+
First, Alice and Bob may each curate different lists of packages that they
68+
trust. For example, the security team at Alice's company has only blessed
69+
specific packages and Alice wishes to install only those packages. Every other
70+
user clearly should not be subject to those constraints.
71+
72+
Second, Alice may be concerned that a full repository compromise may include
73+
the root role. Since the root role in TUF indicates the top-level target's
74+
role key, this compromise can enable the attacker full control of Alice's
75+
namespace. Alice may want to require that the security team at her company
76+
still be used to decide which packages to trust.
77+
78+
Finally, in fact, Alice's company may have dictated that references to
79+
'foo' should all (transparently) refer to a specific in-house
80+
version, which may not match the result of
81+
resolving foo using the repository's top-level targets metadata.
82+
Instead foo should refer to the name that is resolved using Alice’s
83+
company’s targets metadata file as the top-level targets metadata file. This may
84+
also enable Alice to install software which is available on the repository
85+
but would not be trusted by other users.
86+
87+
Note that in all of the above cases, Alice and Bob still want to use the
88+
repository as a means to coordinate and obtain new versions of targets
89+
metadata. They however 1) want control of what packages would be installed
90+
and 2) want to limit the damage caused by a root key compromise on the
91+
repository.
92+
93+
# Rationale
94+
95+
We introduce this TAP because the alternative is slightly onerous. One could
96+
technically achieve the first and second use cases (different curated lists of
97+
packages and additional protection against a compromise of the repository’s
98+
root key) by using delegations to multiple repositories. The way in which this
99+
would work would be to have the security team at Alice's company run their
100+
own repository and for Alice to use a mapping [TAP 4](tap4.md) that indicates
101+
that both the security team and the original repository must be trusted for an
102+
installation to happen. In this way, only software blessed by the security team
103+
may be installed.
104+
105+
However, this does not support the final use case above of transparently
106+
referring to an in-house version. The reason is that
107+
the original repository must also indicate that software is trustworthy, which it
108+
would not in this case. This TAP allows the user to override (i.e., ignore) the
109+
top-level targets metadata. The repository's separate namespace will not
110+
match with Alice's in this case.
111+
112+
# Specification
113+
114+
In order to support this situation, we propose a change to the mapping
115+
metadata to enable the name and key(s) for a targets metadata file to be specified.
116+
This targets metadata file will be uploaded to the repository and will be used as though
117+
it is the top-level targets metadata file by the client instead of the top-level targets
118+
metadata file listed in the repository's root metadata. As is true in all TUF repositories,
119+
all targets metadata files are listed in the snapshot file and benefit from the usual
120+
rollback and similar protections provided.
121+
122+
Note that both the name and the key MUST be specified. If the name
123+
were permitted to be specified without the key, then the repository
124+
would be trusted to serve the correct file, without any offline key attesting
125+
to which keys indicate the targets role.
126+
127+
As such, we add to the [Mechanisms that Assigns Targets to Repositories](https://github.com/theupdateframework/taps/blob/master/tap4.md#mechanism-that-assigns-targets-to-repositories)
128+
support for a reference to the targets file in an identical way to the
129+
root file's reference in the [TUF specification](https://github.com/theupdateframework/specification/blob/master/tuf-spec.md#4-document-formats).
130+
However, additionally, the file name must be specified as this is no longer
131+
targets.json.
132+
133+
Note that the TUF specification's discussions about metadata storage, writing,
134+
and retrieval are not changed by this TAP. The description about how to
135+
(optionally) write consistent snapshots is not changed by this TAP. Consistent
136+
snapshots already require versioned metadata to be available for all targets metadata
137+
files. All targets metadata files (top-level and otherwise) are also stored in the
138+
same METAPATH location listed in snapshot.json.
139+
140+
The changes in the client application workflow are fairly minor from this
141+
TAP. Steps 4.0 and 4.4.0 should refer to the specified target's metadata file instead
142+
of the top-level targets metadata file. Additionally, instead of verifying the targets metadata
143+
file using the key in the root metadata in step 4.0, verification must use the
144+
keys listed in the mapping metadata.
145+
146+
There likely also needs to be a clarity pass throughout to make this potential
147+
use mode clearer in the specification.
148+
149+
From an operational standpoint, a lost targets key for a delegated target could have been
150+
remedied before by the repository but this no longer works. If the repository delegated to
151+
a target from the top-level targets role, that file could be updated if Alice’s key changed or
152+
was lost. However, as the repository’s root role is no longer trusted to provide top-level targets keys, any clients using this
153+
TAP must take more care because the root metadata may not be used to revoke trust in
154+
the targets key. Thus, a user should take into account the operational difficultly to touch
155+
clients in the case of key loss for the top level targets file. If it is operationally difficult to
156+
touch the clients, then the client may perhaps use a threshold of offline keys before delegating to
157+
a developer’s key. [TAP 8](tap8.md) also provides support for cases where the key need to be rotated
158+
or changed and the key is still accessible to the developer.
159+
160+
161+
# Security Analysis
162+
163+
Our overall belief is that this is a security positive change to TUF.
164+
The added complexity from this change is fairly small. The mapping metadata
165+
itself already exists in TUF and this TAP merely makes a small addition to
166+
parameterize the top-level targets role. We feel that implementation errors
167+
with adding this TAP are unlikely to occur. However, the ability to better
168+
control trust should help users to better secure important operational use
169+
cases. We are also unaware of plausible scenarios where this feature would
170+
lead to insecurity due to abuse or misconfiguration except the inability to
171+
have the root role rotate the targets key. However, selectively removing this
172+
capability from the root role is the purpose of this TAP.
173+
174+
# Backwards Compatibility
175+
176+
This TAP does not require clients that do not support this TAP to update.
177+
Hence, all existing clients may continue to update. As the mapping metadata
178+
is controlled on the client device, this will need to be updated along with the
179+
client implementation. The repository metadata does not change in any way.
180+
181+
# Augmented Reference Implementation
182+
183+
[TODO: Point to a branch containing implementation of TAP 13.]
184+
185+
# Copyright
186+
187+
This document has been placed in the public domain.

0 commit comments

Comments
 (0)