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

Jump to bottom

[TAP 8] Update TAP 8 for clarity and changes in the spec #163

Merged
merged 3 commits into from
Jan 6, 2023
Merged

[TAP 8] Update TAP 8 for clarity and changes in the spec #163

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
baea74b
[TAP 8] Update for clarification and spec changes
mnm678 Nov 17, 2022
024f60a
clarifications from code review
mnm678 Jan 4, 2023
424df95
fix line lengths
mnm678 Jan 4, 2023
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
175 changes: 85 additions & 90 deletions tap8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
* TAP: 8
* Title: Key rotation and explicit self-revocation
* Version: 2
* Last-Modified: 19-Sep-2018
* Last-Modified: 16-Nov-2022
* Author: Hannes Mehnert, Justin Cappos, Marina Moore
* Status: Draft
* Content-Type: text/markdown
Expand All @@ -28,38 +28,34 @@ root role. The root role will continue to use the root metadata to establish
a trusted root key.

Conceptually, the rotation process says if you trusted threshold of keys
X_0, ... X_n, now instead trust threshold of keys Y_0, ... Y_n. Rotation of a
key may be performed any number of times, transferring trust from X to Y, then
X = X_0, ... X_n, now instead trust threshold of keys Y = Y_0, ... Y_n. Rotation
of a key may be performed any number of times, transferring trust from X to Y, then
from Y to Z, etc. Trust can even be transferred back from Z to X, allowing a key
to be added to a role, then later removed.

The mechanism in this TAP has an additional use case: if a rotation
to a null key is detected, it causes the role to no longer be trusted.
A role could use a rotation to a null key if they suspect a compromised key
to a null key is detected, it causes the role to no longer be trusted.
A role could use a rotation to a null key if they suspect a threshold of keys
have been compromised
(a lost hard drive, system breach, etc). The role is able to create a
rotation to null without the help of the delegator, so they are able to
explicitly revoke trust in the role immediately, improving response time
to a key compromise. A rotation to a null key revokes trust in the role,
not specific keys, so all keys associated with the role will be invalid
after a rotation to null. The client will detect a rotation to a null key
and treat it as if the delegation was missing a key. The rest of the
delegator's file would still be valid.

The delegator is able to recover from a rotation to null by delegating
to a new role. The role that has been self revoked can no longer be used.
Additionally, a delegator can overrule a rotate file by delegating to a
new role. This ensures that the delegator still has the root of trust,
but allows the role to act independently. The exception to this is the roles
defined in the TUF spec (timestamp, snapshot, etc). These roles cannot be
delegated to a different rolename, so the root role can delegate to the same
role with a different key to recover from a rotate to null. The root role
is responsible for ensuring that the current chain of trust is valid
(this process is described in detail below).
after a rotation to null. If only a single key needs to be replaced, it can be
safely rotated using the mechanism in this TAP. The client will detect a rotation
to a null key and treat it as if the metadata was unsigned.

A delegator to a role A is able to help A recover from a rotation to null of A by
delegating to a new set of keys for A.
Additionally, a delegator can overrule a rotate file by delegating to the role
with a new set of keys. This ensures that the delegator is still the source of
trust, but allows the role to act independently.


# Motivation

TUF supports key rotation for the root keys using an ad hoc way.
TUF supports key rotation for the root keys using an ad hoc method.
Several use cases can benefit from a generalized mechanism:


Expand Down Expand Up @@ -88,29 +84,26 @@ key, and rotate these keys in and out without going through the delegator.
## Why root key rotation is not supported

TAP 8 provides a methodology for key rotations for roles other than root,
leaving the root rotation mechanism in place.

Root key rotation cannot use the TAP 8 rotation mechanism to establish a
trusted key. The root metadata file contains information, like the
spec-version, that needs to be seen for each version of the file. This
means that even if the keys are not changed, a client must download every
version of the root metadata in order to ensure the client spec-version is
in line with the server spec-version.
leaving the root rotation mechanism in place. The root metadata file contains
information, like the spec-version, that needs to be seen for each version of
the file. This means that even if the keys are not changed, a client must
download every version of the root metadata in order to ensure the client
spec-version is in line with the server spec-version.

## Auto-rotation timestamp role

Roles which typically have short lived keys, like the timestamp role,
may wish to revoke trust in the prior key and sign a new key with the
old. This limits the ability for attackers to walk back the set of
trusted keys. Right now, there is no good way to do this within TUF,
which may result in some keys being trusted more than they should be.
which may result in some keys being trusted longer than they should be.

Using TAP 8, the online key can rotate itself without a signature by the
offline key.
offline root key.

Note, this TAP is not meant to address all situations where keys will
change. If there is a scenario where new keys are generated and
delegated to by a master key this model remains the same as in TUF
delegated to by a delegating role this model remains the same as in TUF
today. For example a HSM may generate and sign new timestamp keys every
hour. Since the HSM's key does not change, this is not a rotation and
thus is not intended to be handled by this TAP.
Expand All @@ -121,17 +114,17 @@ thus is not intended to be handled by this TAP.
TUF is a framework for securing software update systems that is designed
to maintain trust in the system through key compromises. The trust
is rooted in a quorum of root keys, which delegate trust to other roles.
When the root keys delegate trust to a role t for all names, this can be
used to delegate some names to role d, etc. When the person who owns
role d wants to renew their key, they have until now had to ask the holder of
role t to delegate to the new keyset e. If one of role d's keys is
compromised, they have to wait for role t to replace the key with a new,
When the root keys delegate trust to a role T for all names, this can be
used to delegate some names to role D, etc. When the person who owns
role D wants to renew their key, they have until now had to ask the holder of
role T to delegate to the new keyset e. If one of role D's keys is
compromised, they have to wait for role T to replace the key with a new,
trusted key.

With this proposal, the owner of role d can renew their own key, and also
With this proposal, the owner of role D can replace their own key, and also
revoke their key without relying on the delegator. This will improve
response time to key compromises and allow keys to be rotated more
regularly. Combined with multi-role delegations this allows
response time to key compromises and prevent key sharing by allowing keys to be
rotated more regularly. Combined with multi-role delegations this allows
project teams to shrink and grow without delegation to a project key.

TUF already contains a key rotation mechanism, which is only specified
Expand All @@ -149,8 +142,8 @@ delegations keep intact, the targets can rotate keys, shrink or grow.

## Rotate file

The signed portion of a `rotate` file is as follows (there's as well a
signatures part as in tuf spec, not shown here):
The signed portion of a `rotate` file is as follows (there's also a
signatures wrapper as in tuf spec, not shown here):

```python
{
Expand All @@ -175,14 +168,16 @@ it is meant to be signed once and never modified. The rotate
file has to be signed with an old threshold of old keys.

The rotate file will go into a repository in a 'rotate' folder that contains
all rotate files for the repository.
all rotate files for the repository. These files will be listed in snapshot
metadata for the repository so that the client can verify that they recieve
all current rotate files.

Let's consider a motivating example, project foo is delegated to Alice.
Alice's computer with the key material got stolen, but the disk was
encrypted. To be safe, she decides to get her key from her backup and
roll over her key to a fresh one. To do that, she creates a file
`foo.rotate.ID.PREV`. This file contains her new key, a threshold of 1, and
signed with her old key. She signs her targets file with the new key,
is signed with her old key. She signs her targets file with the new key,
and uploads both the rotate file and the freshly signed targets file to
the repository.

Expand All @@ -196,70 +191,68 @@ The second suffix, referred to as 'PREV' is a SHA256 hash of the previous
rotate file, or the empty string if there is no previous rotate file.
This prevents rotation cycles.

The existing delegation to Alice's old key is still valid. If the delegation
is changed to include her new key, it will also be valid. The client uses
whichever key is delegated to to find the current chain of trust, then
follow that chain to the last rotate file to find the current trusted key.
The existing delegation to Alice's old key is still valid. The client will
start with this delegation and look for rotation files to determine the current
set of trusted keys.

If the delegation is changed to include her new key, it will also be valid. Any
old rotate files for this role should be deleted and removed from snapshot on
the next snapshot key rotation. The client will determine the correct rotate file
to begin the chain using the set of keys in the delegation for the role as the `ID`.

## Client workflow

A client who wants to install foo now fetches Alice's targets file, and
during verification looks for a file named `foo.rotate.ID.PREV` in the
rotate folder, ID and PREV are explained above using Alice's old keyid.
rotate folder, ID and PREV are explained above using Alice's old keyid.
The client sees the file, fetches
it and verifies this rotate file using the public key from the delegation.
it and verifies this rotate file using the public key from the delegation.
The client then looks for a rotate file with the new keyid, repeating until
there is no matching rotate file to ensure up to date key information. This
establishes trust in Alice's new key, and the client can now verify the
signature of Alice's targets file using the new key. If key data is missing
or there is a rotation to null the targets file is invalid.
or there is a rotation to null the targets file is invalid and the client will
proceed with the update process as if verification for this file failed.

## Timestamp and snapshot rotation

Timestamp and snapshot key rotation. These keys can rotate as
well, leading to ROLE.rotate.ID.PREV files, where ID and PREV are as described above.
The value of T is the ASCII encoded old threshold value. Each file is
signed by a quorum of old keys, and contains the new keys. A client
can fetch the actual data, timestamp, and verify it. During verification,
the client needs to fetch the ROLE.rotate.ID.PREV file
where ID is as described above using the timestamp keyid, either from
the root file or locally cached and PREV is as described using the previous
timestamp rotate file or null. If the timestamp key is renewed by
Timestamp and snapshot keys can rotate as well, leading to ROLE.rotate.ID.PREV
files, where ID and PREV are as described above. Each file is signed by a quorum
of old keys, and contains the new keys. If the timestamp key is renewed by
the root, all timestamp.rotate files can be safely removed from the
repository.

The root role should ensure that all previous rotate files are removed when
it delegates to a new chain of trust. This ensures that the client sees a
consistent set of rotate files and is able to follow the chain of trust.
it delegates to a new chain of trust. This saves space and simlifies the client
search for rotate files.

## Interoperability with TAP 3 (multi-role delegations)

Multi-role delegations are handled using the same methodology.

Let's consider the project foo, initially delegated to a multi-role
threshold (of 2) to keyids Alice, Bob, and Charlie. When they want
to add a keyid from Dan to the project, they create a foo.rotate.ID.PREV
file, where ID is as described above (the SHA256 of the concatenated
key ids of Alice, Bob, Charlie, and the character 0x32). This
contains all four keys, and a new threshold (again 2). PREV is the
Let's consider the project baz, initially delegated to a multi-role
threshold (of 2) to roles foo, and bar, each of which have a threshold of 2
keys. When they want to add a keyid from Dan to the foo role, the current foo
keyholders create a foo.rotate.ID.PREV file, where ID is as described above (the
SHA256 of the concatenated key ids of foo, and the character 0x32). This contains
all previous foo keys, as well as Dan's key and a new threshold. PREV is the
SHA256 of "" as this is the first rotation for foo. The file
foo.rotate.ID.PREV is signed by at least 2 keyids of Alice, Bob, and Charlie.
foo.rotate.ID.PREV is signed by at least 2 current keyids of foo.
The new targets file foo is then signed by a new threshold (again 2) of
Alice, Bob, Charlie, and Dan to complete the rotation.
the new keyids (including Dan) to complete the rotation.

Let's assume Bob and Dan signed foo. A client which encounters a
delegation to foo first looks for a foo.rotate.ID.PREV file with the
keyids and threshold specified in the delegation file and an initial
value of "" for the previous rotate file. If this file exists and is
properly signed by Alice and Bob, the client uses it to fetch new keys.
properly signed by Alice and Bob, the client uses it to fetch new keys.
The client can then verify foo using Bob's and Dan's signature.

When Evelyn joins, and the threshold is increased to 3,
foo.rotate.ID'.PREV' is created (ID' is the SHA256 of the concatenated keyids
Alice, Bob, Charlie, Dan, and 0x32, PREV' is the SHA256 of the previous
rotate file), which contains Alice, Bob,
Charlie, Dan, and Evelyn public key, and a threshold value of 3. This
is signed with at least 2 keys from Alice, Bob, Charlie, or Dan.
foo.rotate.ID'.PREV' is created (ID' is the SHA256 of the concatenated old keyids,
and 0x32, PREV' is the SHA256 of the previous rotate file), which contains the
existing keyids as well as Evelyn's public key, and a threshold value of 3. This
is signed with at least 2 keys from the current set of keyids.

## Rotation to Null

Expand All @@ -268,37 +261,35 @@ to a rotation to a null key is invalid. The null key is a hard coded value used
tuf implementations. This enables a role to explicitly revoke their
own key(s) by introducing a rotation to null.

The rotate files will be listed in the snapshot metadata and shall be
downloaded as soon as they are available.

**Prioritizing Self Revocation**
Rotation files are immutable unless replaced with a revocation (rotate
to null). This is the only case in which they can be replaced or
modified. If a client wants to rotate to a different
key, without having access to their currently delegated private key,
this requires a key revocation by the person one higher in the
delegation chain.
this requires a key revocation by the delegating metadata.

Possibly rotations which do not have any entry point anymore can be
safely removed from the repository - if the delegation of foo is
Rotations which do not have any entry point anymore (the delegation they
stem from has can been replaced with new keys) can be
safely removed from the repository. If the delegation of foo is
directly done to Alice, Bob, Charlie and Dan with a threshold of 2
(e.g. the delegation expired, and the person in charge decided to
directly trust this team), the foo.rotate files can be safely removed.
This is tricky in respect to TAP 4 and TAP 5.

# Security Analysis

There should be no negative security impact. The major benefits are
that many security-sensitive operations that required key use by
that many security-sensitive operations that require key use by
multiple parties, will now be much easier to do. This will
provide a simple mechanism extending and shrinking projects by
themselves without an individual with elevated privileges, but based
provide a simple mechanism for extending and shrinking project membership
without an individual with elevated privileges, but based
on a threshold of signatures.

Clients need to take care to check for rotation to a null key (rotate
files that contain a null key). This shall be handled in the
same manner as an invalid metadata signature on by the role possessing
the key. The role will be invalid until it is re-delegated to.
the key. The role will be invalid until it is re-delegated to with a new key.
Clients MUST use snapshot metadata to ensure that they recieve all rotate files
in the chain.

Intentionally rotating to null enables a repository, a
project, and individuals to explicitly revoke their key material
Expand All @@ -309,8 +300,10 @@ For mitigation of private key compromises, rotation can be used if and
only if it can be assured that the legitimate holder is faster (at the
snapshot service, and/or at the client) than the attacker who got
control over the private key. Because this is hard to achieve, it is
recommended for proper mitigation that the delegation is changed from
the compromised key to a new key.
recommended for proper mitigation that the delegation itself is changed from
the compromised key to a new key as soon as possible. Key revocation using
rotation defined in this TAP can be used as a stop-gap for delegations made
by offline keys that may take some time to update.

As a general note, this TAP only extends the possibilities of a target,
but the delegation mechanism is still in place - i.e. a key higher up
Expand All @@ -321,7 +314,9 @@ Infrastructure - http://people.scs.carleton.ca/~paulv/papers/wisec2014-baton.pdf
- is a similar proposal to extend Android's signing infrastructure.
The main differences is that they put the old _and_ new keys in
the token, whereas we only put the new keys inside, since the old
keyids are already listed in the delegation.
keyids are already listed in the delegation. Our proposal also takes advantage
of the existing delegation model in TUF to allow for thresholds of signatures
and revocation by a more trusted role.

Clashes of rotate file names are unlikely - the role is the first
element, followed by "rotate", all key ids in alphabetical order,
Expand Down