-
Notifications
You must be signed in to change notification settings - Fork 267
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document ADR 0008 about unrecognized fields
Even though, this ADR documents something already implied in the TUF spec in [document formats](https://theupdateframework.github.io/specification/latest/#document-formats) it seems better to document this decision clearly so that it could be referenced and give an explanation why someone can load a metadata file with additional unrecognized fields. Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
- Loading branch information
Showing
1 changed file
with
44 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
# Accept metadata that includes unrecognised fields | ||
|
||
- Status: accepted | ||
- Date: 2021-04-08 | ||
|
||
Technical Story: https://github.com/theupdateframework/tuf/issues/1266 | ||
|
||
## Context and Problem Statement | ||
|
||
The current reference implementation will ignore unrecognized fields in a | ||
metadata file when loading it. | ||
This leads to the side effect that if you read a metadata file with unrecognized | ||
fields and imidiatly write it back to the disk, this file will be modified. | ||
|
||
Furthermore, some TAPs ([6](https://github.com/theupdateframework/taps/blob/master/tap6.md), [10](https://github.com/theupdateframework/taps/blob/master/tap10.md), [14](https://github.com/theupdateframework/taps/blob/master/tap14.md), [15](https://github.com/theupdateframework/taps/blob/master/tap15.md), and [16](https://github.com/theupdateframework/taps/blob/master/tap16.md)) are relying on that unrecognized | ||
fields will be accepted to introduce new fields to the specification without | ||
making the metadata invalid for older clients which don't recognize the field. | ||
|
||
## Decision Drivers | ||
- The TUF specification implies support for custom attribute-value fields | ||
See [Document formats](https://theupdateframework.github.io/specification/latest/#document-formats) | ||
- Backward compatibility | ||
- If we perform the following operations on a metadata file with no | ||
intermediate operations: | ||
1. read the metadata file | ||
2. write the metadata file back to the disk | ||
the checksum (the content) of the file must not be changed. | ||
- Flexibility to add new fields in the spec without adding breaking changes. | ||
|
||
## Considered Options | ||
- Ignore and drop unrecognized fields. | ||
- Ignore, but store unrecognized fields as an additional attribute. | ||
|
||
## Decision Outcome | ||
|
||
Chosen option: "Ignore, but store unrecognized fields as an additional | ||
attribute." | ||
The motivations for this decision are that the TUF specification already implies | ||
that we should accept unrecognized fields for backward compatibility and easier | ||
future extensibility. | ||
|
||
Additionally, it seems unacceptable to change a metadata file content just by | ||
reading and writing it back. | ||
|