Add Reference field type

[marcelamelara]

This PR adds a new primitive field type for artifact references. and changes the type of the subject field in the Statement to this new type.

Related to #2 and #27. Addresses #117. Part of #130 .

[TomHennen]

Would it make sense to put this in the v1.0-draft spec instead of here with 0.1?

[marcelamelara]

@TomHennen Yes! So I wanted to figure out what the best order of operations is between this merging PR and #132. I think we should merge yours first, and I'll rebase on that then. Thoughts?

[TomHennen]

Yeah that sounds right. :)

[TomHennen]

@MarkLodato you might have thoughts here

[MarkLodato]

What is the purpose of this change? What use case is this enabling that cannot be done before? That is not explained in the PR description, and it's not clear to me.

As I have said previously, I think the clearest, simplest model is that an attestation is about an immutable thing that can be hashed. Extending it to represent a subject that is mutable makes it more confusing. Before going down that road, I'd like to see what the use case is and consider what the alternatives are.

[TomHennen]

What is the purpose of this change? What use case is this enabling that cannot be done before? That is not explained in the PR description, and it's not clear to me.

As I have said previously, I think the clearest, simplest model is that an attestation is about an immutable thing that can be hashed. Extending it to represent a subject that is mutable makes it more confusing. Before going down that road, I'd like to see what the use case is and consider what the alternatives are.

I'm not the expert in what's going on with SLSA, but I think a good example of an attestation about something that can't be hashed is a statement that refers to a builder ID.

I could imagine:

"subject": [{"uri": "https://cloudbuild.googleapis.com/GoogleHostedWorker@v1"}],
"predicateType": "https://example.com/slsa-build-level",
"predicate": {
    "attestorId": "https://slsa-conformance.dev",
    "slsaLevel": "LEVEL_3"
}

Which says that https://slsa-conformance.dev has confirmed that the builder identified by https://cloudbuild.googleapis.com/GoogleHostedWorker@v1 has been verified to be SLSA L3.

[marcelamelara]

@MarkLodato My main reasoning for changing the subject's type is to enable verifiers to download the subject if they do not obtain the attestation together with the subject artifact.

My initial proposal in #117 included only the digest and downloadLocation fields because I agree that matching should occur on digest, not on URI. (Yes, given your explanation, I totally agree that SBOM, logs, etc are all artifacts). This is also the reason I am generally on the fence about having both digest and uri fields, but I wanted to start off with the current SLSA v1 ArtifactReference format and take it from there.

@TomHennen In your example, does the URI for the builderID actually point to an underlying artifact?

[TomHennen]

@TomHennen In your example, does the URI for the builderID actually point to an underlying artifact?

No not necessarily,.

If we want to go the easy route we could:

1. Define ArtifactReference (or whatever) as a type
2. Leave subject as it currently is (just name & digest)
3. Enhance subject as needed in some future revision.

I think this would unblock all the current concrete needs?

[marcelamelara]

@TomHennen I'm starting to think it might be worth handling artifact and service references (like the one in your example) through separate field types.

Since the current subject field already doesn't support service-type references, I don't think that expanding it to an ArtifactReference type would really break the current semantics, while still providing the extra downloadLocation and mimeType fields (and not adding the uri field). We can resolve adding support for service-references in subjects at a later point. Thoughts?

[TomHennen]

That sounds good to me.

[MarkLodato]

To clarify, my only main concern is semantics of the subject. If there is clear documentation, I'm (probably) good. Something like:

"The attestation is bound to either subject.digest or subject.uri. Exactly one of these fields is required for each entry in subject. All other fields are informational."

As an analogy, consider car ownership. The title is like an attestation whose subject is the VIN. There are lots of other identifying details about the car in the title, such as the make, model, color, weight, etc., but the only thing "binding" is the VIN. When you want to look up a car's ownership, you only compare the car's VIN to the title's VIN. The other attributes are irrelevant (though useful in other contexts). Similarly, if you're referring to a car, you might say "That red Honda CR-V located on that side of the street, with license plate ABCXYZ and VIN 1234"; this has useful information in it, but only the VIN is used to compare to the title.

[marcelamelara]

@MarkLodato Thanks for the clarification and language suggestions.

I've pushed some updates based on our discussions. For now, we've decided to defer changing the subject field type since we don't have any concrete use cases for a reference-type subject just yet. I've also removed the uri field to make the reference specifically for hashable artifacts. We'll address referencing non-hashable resources separately.

[marcelamelara]

Closing in favor of #143.