improve software integrity and verification documentation

[jeff-schutt]

Improves documentation in the SPDX 3 model to direct users towards existing support for package verification.

RE: #345 (comment)

CC: @goneall

[goneall]

One suggestion and one question for @zvr on spec parser support for the subheadings.

[kestewart]

Bob and Dick to take a pass through this, per call today.

[rjb4standards]

I concur with Gary's proposed language. It may be worth noting that component ordering can effect OmniBor results. SBOM's have no implied ordering requirement and may not be easily "verifiable" using OmniBor due to this mismatch in ordering requirements.

[zvr]

Obviously is not only a "gitoid", but any content identifier.

[rjb4standards]

It may be more appropriate to include an identifier tag in the syntax, like IANA uses to qualify identifier types - similar to what SPDX does today : dns:www.foo.com SHA256:.......

[kestewart]

There are other content identifiers out there, as Alexios points out. Let's handle the broadening as a separate PR though, and move this forward. The original had gitoid in it, and is just restructured here.

[zvr]

Suggested change

	Used by SPDX producers to record the artifact’s gitoid: a canonical, unique, immutable identifier that can be used for software integrity verification.
	Used to record a canonical, unique, immutable identifier of the artifact, that can be used for verification its identity and integrity.

[zvr]

Suggested change

Used by SPDX consumers to verify the integrity of a software artifact they received.

No need to have it separate for producers/consumers.

[zvr]

I disagree that contentIdentifier has to be a gitoid. We should leave it for any kind of unique identifier.

[goneall]

Note that not all content identifiers support use in verification. We would also need to somehow specify which content identifier is used (e.g. the enumeration of supported content identifiers).

[rjb4standards]

That appears similar to how SPDX handles this today with the SHA* identifying tags accompanying a hash value in an SBOM

[goneall]

@zvr - Let's move forward with this definition and open a separate issue to include better support for SWHID after RC2 - just trying to get RC2 released.

[zvr]

We can remove gitoid and leave generic "unique, immutable artifact identifier" or we can mention both gitoid and swhid that we already know of.

[zvr]

I'm not objecting just because I don't want SWHIDs to be forgotten:
The most important part is, given that we know there might be more than one format, modeling it as a single value (of type URI) will not work. There has to be a type defined somewhere (maybe with a vocabulary), etc.

[sbarnum]

My recollection of the discussions on this topic from last year were that for v3.0 we would specify gitoid as the default but that the structures and definitions would be generalized (as @zvr is suggesting above) to enable addition of other possible types post v3.0 without breaking backward compatibility.

In other words, I agree that the definitions should be generalized and not locked to one approach.

[goneall]

With the updated changes - all looks good

[bobmartin3000]

Agree that the changes addressed the concerns for RC2.

[kestewart]

There are other content identifiers out there, as Alexios points out. Let's handle the broadening as a separate PR though, and move this forward. The original had gitoid in it, and is just restructured here.

[zvr]

I'm not objecting just because I don't want SWHIDs to be forgotten:
The most important part is, given that we know there might be more than one format, modeling it as a single value (of type URI) will not work. There has to be a type defined somewhere (maybe with a vocabulary), etc.

[goneall]

I'm not objecting just because I don't want SWHIDs to be forgotten:
The most important part is, given that we know there might be more than one format, modeling it as a single value (of type URI) will not work. There has to be a type defined somewhere (maybe with a vocabulary), etc.

@zvr - Since the contentIdentifier property defined as a GitOID has been there for a while and making this field accept other formats and/or changing the model for verifiedUsing to a yet to be specified alternative will take some time - do you think we should delay RC2 to resolve this or should we merge this in and discuss as a post RC2 issue?

[zvr]

This should be resolved before RC2, since it most probably will result in changes in the model.
If it was only the description text, we could leave it.

[zvr]

In an effort to resolve the different discussions here, I've broken down the different parts and submitted a number of PRs:

• Updates integrity verification docs in Core #609, to add the wording to the classes and property of Core

and then, an option of two approaches:

• Use gitoid for SoftwareArtifact integrity verification #610 makes gitoid a property to SoftwareArtifact (and we can add others later); or
• Generalize contentIdentifier for SoftwareArtifact integrity verification #611 to make contentIdentifier more general, supporting different types by adding properties and a vocabulary

Note that there is no mention of "preferred", "recommended", "suggested", etc. anywhere. Policy is something different than model definition and can be decided later -- and expressed with various conformance tests, profile definitions, etc.

@goneall , @jeff-schutt , @kestewart and everyone else, please review these new PRs.

[goneall]

In an effort to resolve the different discussions here, I've broken down the different parts and submitted a number of PRs:

• Updates integrity verification docs in Core #609, to add the wording to the classes and property of Core

and then, an option of two approaches:

• Use gitoid for SoftwareArtifact integrity verification #610 makes gitoid a property to SoftwareArtifact (and we can add others later); or
• Generalize contentIdentifier for SoftwareArtifact integrity verification #611 to make contentIdentifier more general, supporting different types by adding properties and a vocabulary

Note that there is no mention of "preferred", "recommended", "suggested", etc. anywhere. Policy is something different than model definition and can be decided later -- and expressed with various conformance tests, profile definitions, etc.

@goneall , @jeff-schutt , @kestewart and everyone else, please review these new PRs.

Thanks @zvr - having the specific pull requests definitely makes it easier to compare / review / decide.

I'm OK with either of your two choices in the model changes. I'm also OK with the current state, but you do raise a good point about contentIdentifier as a name implies a broader range than gitoid, which leans me towards changing the property name as the easiest path forward.

I do like PR #602 as a better starting point for the documentation for reasons noted in the review comments. We should probably decide on the 3 choices of the model -1) keep as is; 2) PR #610 rename the property or 3) PR #611 generalize contentIdentifier.

@jeff-schutt @zvr Since I'm OK with all three approaches, perhaps you can connect and decide which works OK for both of you.

[sbarnum]

I do not think that these sort of case specific details should be placed here.
This is the general structure to be used across SPDX.
Placing case specific variations here is likely to lead to an eventual laundry list of such specializations.

I propose that it would be more appropriate to add this note to the markdown files for the case specific structures (SoftwareArtifact, File, Package, Snippet).

[sbarnum]

I do not think that these sort of case specific details should be placed here.
This is the general structure to be used across SPDX.
Placing case specific variations here is likely to lead to an eventual laundry list of such specializations.

I propose that it would be more appropriate to add this note to the markdown files for the case specific structures (SoftwareArtifact, File, Package, Snippet).

[sbarnum]

I do not think that these sort of case specific details should be placed here.
This is the general structure to be used across SPDX.
Placing case specific variations here is likely to lead to an eventual laundry list of such specializations.

I propose that it would be more appropriate to add this note to the markdown files for the case specific structures (SoftwareArtifact, File, Package, Snippet).

[goneall]

This is a bit stale with the renaming to gitoid - retargeting to post RC2 for discussion

[goneall]

This is now quite stale and there are other PR's which overlap.

I'm going to go ahead and close this PR.

@jeff-schutt @zvr - Please feel free to open a fresh PR if you think the documentation needs to be updated.