Add clarification on unknown key-value pairs in file format

theupdateframework / specification

The Update Framework specification

https://theupdateframework.github.io/specification/

Other

368 stars 54 forks source link

Add clarification on unknown key-value pairs in file format #163

Closed jku closed 3 years ago

jku commented 3 years ago

Spec says:

All of the formats described below include the ability to add more attribute-value fields for backwards-compatible format changes.

This does not make it very clear

that anyone de/serializing the format needs to be able to cope with undefined key-value pairs in various places in the file format: those key-value pairs are part of the data for the purposes of calculating hashes or signatures and MUST then be preserved if data is re-serialized
where those key-value pairs can appear

My own understanding of the last point is that they can appear in every "object-like" dictionary at or below signed, meaning every dictionary in the format except ["hashes", "keys", "meta", "roles", "targets"].

asraa commented 3 years ago

Nice! I have a use case for unknown key-values that @trishankatdatadog linked this issue to.

I completely agree that these key-value pairs must be preserved by an implementation so that hash/signature calculations can be consistent.

As far as where they can appear: my personal use case is key-values that may appear as auxiliary information in the KEYVAL dictionary (https://theupdateframework.github.io/specification/latest/#keyval). My linked PR adds a custom dictionary to this to append additional public key information (a certificate attesting to the public key).

trishankatdatadog commented 3 years ago

Thanks, Asra! I think the next step is to add some text to the spec to clarify how to preserve and yet ignore these superset fields...

asraa commented 3 years ago

Would it suffice to have it be similar to CUSTOM in targets (opaque to implementation, as a json object) and submit a PR in this repo with the change?

trishankatdatadog commented 3 years ago

I don't think we even need to mention any specific field 🙂 We can add CUSTOM and your field as examples, but the important thing is to advise implementations what to do when seeing these added/superset fields. Makes sense?