Add Rekor body to TransparencyLogEntry

[codysoyland]

Summary

This adds the canonicalized Rekor body field to the TransparencyLogEntry message. This allows us to verify the SET without reconstructing the body, in cases where the client doesn't have enough data to deterministically reconstruct it.

This doesn't excuse the client from deserializing and verifying the data inside the body. It is still the responsibility of the client to verify that any payload hashes, certificates, and signatures match those in the Sigstore Bundle. The verification spec should make this explicit (cc @kommendorkapten).

The version has been incremented to 0.2.

Fixes #9

Release Note

Documentation

[znewman01]

What are verifiers expected to check, here?

Do they need to parse the body? (Seems like yes, otherwise you could pass literally any entry)

What do they need to check about the ultimately parsed body?

[znewman01]

Hm, I think I was expecting this to go directly under "bundle".

What happens if there's >1 transparency log entry and they have mismatching bodies?

[znewman01]

We had a similar conversation on the initial draft: sigstore/cosign#2204 (comment)

I'm still vaguely in favor of moving KindVersion out but don't feel super strongly

[kommendorkapten]

How about renaming body to canonicalized_body to be more clear what the body is?

[kommendorkapten]

@znewman01 @haydentherapper

Hm, I think I was expecting this to go directly under "bundle".

I think yes and no here. From a bundle verification perspective it makes sense to not include such data in the TransparencyLogEntry, as it's expected to be the same for all entries on all logs.
My reason against it, is that the current TransparencyLogEntry is also intended to represent a response from the log, so it's a bit of a dual purpose right now. For now I would favour the current case, where some data are repeated.

An alternative (say for next release) could be to create a "multi log entry" which has a single kind/version, and then an array of the non-invariant details from each log.
I'm not sure about the value of doing that now, as I guess majority of clients will rely on the canonicalized body to verify the SET.
But when we have SET v2 where the payload is easy to reconstruct, having the invariant data out of the log entry will IMHO make the verification process stronger, as it will force each entry to have the same kind/version without any explicit logic for it (assuming that kind/version is part of the payload the SET is constructed over).

edit: s/now/no/

[znewman01]

CC @kommendorkapten what are the expectations around versioning here?

I feel like the plan is to make a bunch of breaking changes to the bundle in the very near future, is it worth even versioning it? Should we add a release process?

[haydentherapper]

i think no versioning at this point, this isn't being used anywhere. break away!

[kommendorkapten]

Agreed, ignore versioning for now, we are still in the early days.

What I think might be the next major release is when Rekor SET v2 is out, then we should drop the raw Rekor respone, as it will be much easier/deterministic to verify the SET from a client perspective.

[codysoyland]

I'm not sure when is the right time to add versioning, but what if we change this version specifier to contain the string alpha to emphasize that it's unstable? e.g.version=0.1-alpha.

[kommendorkapten]

When we see the first real usage of the bundle (which I think is the npm use-case) in the wild, I think we can consider it released. I think it's too early to mess with this now. Ok, I know that's a bit underspecified but when we see a stable development for npm, which I hope is pretty soon, we can cut a release.

[codysoyland]

What are verifiers expected to check, here?

Do they need to parse the body? (Seems like yes, otherwise you could pass literally any entry)

What do they need to check about the ultimately parsed body?

Really, the SET verification is two parts:

• Cryptographic verification of SET, which is a signature over:
  • log index
  • log id
  • integrated time
  • canonicalized rekor body
• Verifying that the attached Rekor entry in fact references the artifact or attestation you are verifying

The first part is fairly straightforward, especially with this PR (as you don't have to "reconstruct" the canonicalized body). It depends on json canonicalization and there is an implementation in cosign.

The second part is more complex, and unfortunately unavoidable if we need to trust the inclusion promise. The fields to check depend on the rekor type. There is also an implementation of this in cosign, which I helped write in response to this security advisory.

Until we have a "SET v2", I suspect we'll need to codify the rules for verifying each rekor type/version combo individually. Probably a limited set to support including intoto and hashedrekord.

[asraa]

+1 to Cody's response above:

I suspect we'll need to codify the rules for verifying each rekor type/version combo individually. Probably a limited set to support including intoto and hashedrekord.

This is likely a good start, if Rekor v2 is upcoming, then no need to overcomplicate type specific impls when that may not exist.

The second part is more complex, and unfortunately unavoidable if we need to trust the inclusion promise.

Technically, the signature fields (type specific extractions) are a MUST compare. I went through a pretty detailed exercise on why. Comparing public keys/cert fields is a MAY/SHOULD, since technically one could extract a public key from a cert and still re-use the same signature (since signature implies the private key material), but in that case it won't impact security. Comparing the payload is also a MAY/SHOULD, since again, it is implied. +1, I think Cody understands the scope!

[kommendorkapten]

🚀

[codysoyland]

I think we have consensus on this... Do any of you with access rights want to merge it?

[kommendorkapten]

Of course!