Document required client changes for Rekor v2

[Hayden-IO]

Fixes #108

Summary

Release Note

Documentation

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 38.00%. Comparing base (b64cdc9) to head (f9286af).
Report is 29 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #255      +/-   ##
==========================================
- Coverage   38.25%   38.00%   -0.26%     
==========================================
  Files          40       41       +1     
  Lines        2883     2963      +80     
==========================================
+ Hits         1103     1126      +23     
- Misses       1676     1731      +55     
- Partials      104      106       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Hayden-IO]

Proposing we change how clients find the correct tlog to use to verify a proof, in sigstore/protobuf-specs#629. Will wait for reviews before updating this doc.

Edit: Added

[jku]

I think the one case where I'm not confident is where the v2 rekor instance is added to signing config:

• before any clients are updated this is straight forward: clients keep signing with v1, nothing breaks
• when client A is upgraded to support v2, the docs seem to imply that it should then only use the v2 instance when the signingconfig includes one (correct?)
• this leads to a client incompatibility if other clients are not able to verify rekor v2 at this point yet

Basically we may need to confirm verification support across the ecosystem before we make signingconfig changes where a rekor v2 instance is enabled

[Hayden-IO]

I think the one case where I'm not confident is where the v2 rekor instance is added to signing config:

• before any clients are updated this is straight forward: clients keep signing with v1, nothing breaks
• when client A is upgraded to support v2, the docs seem to imply that it should then only use the v2 instance when the signingconfig includes one (correct?)
• this leads to a client incompatibility if other clients are not able to verify rekor v2 at this point yet

Basically we may need to confirm verification support across the ecosystem before we make signingconfig changes where a rekor v2 instance is enabled

cc @loosebazooka for something to discuss at the client meeting

This is a consequence of making a TLE v2 struct unfortunately, though even if we didn't, not all clients support signed timestamps so a TLE without an integrated timestamp wouldn't be verifiable anyways - there would have been incompatibility regardless. There will be a period in which some clients (-ruby and -js) will not be able to verify bundles produced by other clients.

I'd like to chat more with GitHub to understand how much cross-compatibility we need between -js and -go for artifact attestations, if any is actually needed.

[jku]

This would be a good place to include the details of what changes in the log entry "canonical_body", and how clients need to handle it -- I'm not sure what exactly is needed but I'm leaving this as reminder based on sigstore/protobuf-specs#632 (comment)

[Hayden-IO]

Note to self: Split into changes for signingconfig, trustroot, and bundle. Add KindVersion and log ID (which is not hex-encoded, unlike rekor v1). Specify how clients should read InclusionProof, ignoring the index (which is always the same as the bundle index) and reading tree size and root hash from the checkpoint.

Edit: Done

[Hayden-IO]

Thanks everyone for comments! I've addressed all comments now. The primary changes are adding a section on entry parsing, some details about bundle-related changes, more info about log instance lookup in the trusted root, and a section on testing against a real instance using curl. The SigningConfig documentation has also been updated in the protobuf-specs repo, it's linked here.

[jku]

This looks great, no notes from me after reading through it twice. Thanks for polishing.

[Hayden-IO]

Merging now, will update based on API changes in a follow up.