Add pkg verification code + checksum clarification

There had been some confusion around when to use the Package
verification code field vs Package checksum. A small group of us got
together and tried to provide more clarity around the two fields in a
new section, Annex K.3 Verifying SPDX Packages. We also updated the
`Description` and `Intent` fields for sections 7.9 and 7.10.

Signed-off-by: Jeff Schutt <[email protected]>
Signed-off-by: Ivana Atanasova <[email protected]>
Signed-off-by: Nisha Kumar <[email protected]>
Signed-off-by: Gary ONeall <[email protected]>
Signed-off-by: Adolfo Veytia <[email protected]>
Signed-off-by: Rose Judge <[email protected]>

Author: rnjudge

chapters/how-to-use.md

@@ -228,3 +228,60 @@ The SPDX Specification contains fields able to address each of the NTIA minimum
 | Unique Identifier | (7.2) Package SPDX Identifier <br>(6.5) SPDX Document Namespace</br> |
 | Relationship | (11.1) Relationship: `CONTAINS`, `DESCRIBES` <br>The document must `DESCRIBES` at least one package.</br> |
 | Timestamp | (6.9) Created |
+
+
+## K.3 Verifying SPDX Packages
+
+Several use cases for SPDX depend on the consumer being able to verify the provenance and integrity of their software. SPDX can support several different scenarios depending on what information is available to the producer, what information is available to the consumer, and how the SPDX document is delivered. These scenarios are described below along with recommended approaches to verifying the SPDX packages.
+
+### K.3.1 General Guidance
+
+If a Package can be represented as a single blob of bytes, such as a tar archive:
+  * `PackageChecksum` must be computed by applying one of the supported hashing algorithms to the package blob.
+  * `PackageDownloadLocation` should be a download locator that retrieves the package blob.
+  * A supplier can define a `PackageChecksum` in a Package without providing a `PackageDownloadLocation`. This lets consumers perform an offline verification of private blobs.
+
+If a Package represents an artifact that logically binds a number of single files together (such as a zip file or a directory):
+  * If the files bound by the Package are described in the document, `PackageVerificationCode` should be computed by using the files' [SHA1](https://www.rfc-editor.org/rfc/rfc3174) checksums. Additionally, the `FilesAnalyzed` field in the Package **MUST** be set to `true`.
+  * If the SHA1 checksum of any files bound by the Package is not available or the File needs to be excluded from the computation, it MUST be marked so by appending `(excludes: FileName)` at the end of the package verification code value.
+
+
+### K.3.2 Examples
+
+#### K.3.2.1 SPDX Package and SPDX Document both contained in Archive File
+Examples include: tarball binding one or more files to a SPDX package, installation file which installs the package and extracts SPDX document in the same directory
+
+SPDX Field To Use: [7.9 Package verification code](package-information.md#79-package-verification-code-field-)
+
+Guidance:
+  * With the SPDX document included in the archive, it is not possible for the SPDX document to include a checksum for the archive itself. Generate a Package verification code and include the SPDX Document file name in the Excluded Files field.
+
+
+#### K.3.2.2 SPDX Package Delivered as an Archive File Separate from the SPDX Document
+Examples include: tarball, installation file
+
+SPDX Field to Use: [7.10 Package checksum](package-information.md#710-package-checksum-field-)
+
+Guidance: 
+  * Generate a checksum for the archive file and include it in the SPDX Package checksum field. The archive file name should also be included in the [Package file name](package-information.md#74-package-file-name-field-) field.
+  * If source files for the Package are included in the Package distribution archive, the Package verification code for that Package should also be included in the SPDX document and the [Files analyzed](package-information.md#78-files-analyzed-field-) field should be set to `true`.
+
+#### K.3.2.3 A Single File Represented as a SPDX Package
+
+Examples include: tarball, binary image, single executable
+
+SPDX Field To Use: [7.10 Package checksum](package-information.md#710-package-checksum-field-)
+
+Guidance: 
+  * If a [Package download location](package-information.md#77-package-download-location-field-) exists, the Package checksum should be the cryptographic hash of the Package blob at the Package download location specified.
+  * If the Package download location is not known, not available, or not accessible to the software consumer, the producer should include a Package checksum for the included Package file.
+
+
+#### K.3.2.4 Directory of Software Represented as a SPDX Package
+
+Examples include: source code, containers
+
+SPDX Field To Use: [7.9 Package verification code](package-information.md#79-package-verification-code-field-)
+
+Guidance:
+  * Include [File name](file-information.md#81-file-name-field-) field in the SPDX document for every file in the directory, include each file’s cryptographic hash as a [File checksum](file-information.md#84-file-checksum-field-), create a [CONTAINS relationship](relationships-between-SPDX-elements.md#111-relationship-field-) between the Package and the files, and set [Files analyzed](package-information.md#78-files-analyzed-field-) to `true` on the Package. **Note**: if Files analyzed is set to `false` you __cannot__ provide a Package verification code.

chapters/package-information.md

@@ -629,7 +629,7 @@ EXAMPLE 2 RDF: Property `spdx:filesAnalyzed` in class `spdx:Package`
 
 ### 7.9.1 Description
 
-This field provides an independently reproducible mechanism identifying specific contents of a package based on the actual files (except the SPDX document itself, if it is included in the package) that make up each package and that correlates to the data in this SPDX document. This identifier enables a recipient to determine if any file in the original package (that the analysis was done on) has been changed and permits inclusion of an SPDX document as part of a package. The metadata for the package verification code field is shown in Table 21.
+This field provides an independently reproducible mechanism that permits unique identification of a package and the files contained within it (except the SPDX document itself, if it is included in the package). The metadata for the package verification code field is shown in Table 21. For more specific use cases and examples of how to apply the package verification code field, see [Annex K.3 Verifying SPDX Packages](how-to-use.md#k3-verifying-spdx-packages).
 
 **Table 21 — Metadata for the package verification code field**
 
@@ -662,7 +662,7 @@ Required sort order: '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e'
 
 ### 7.9.2 Intent
 
-Provide a unique identifier based on the files inside each package, eliminating confusion over which version or modification of a specific package the SPDX document refers to. This field also permits embedding the SPDX document within the package without altering the identifier.
+Identify, based on the files inside each package, which version or modification of a specific package the SPDX document references. This field also permits embedding the SPDX document within the package without altering the identifier. This identifier enables a recipient to determine which, if any, files in the original package have been changed.
 
 ### 7.9.3 Examples
 
@@ -695,7 +695,7 @@ EXAMPLE 2 RDF: Properties `spdx:packageVerificationCodeValue`, `spdx:packageVeri
 
 ### 7.10.1 Description
 
-Provide an independently reproducible mechanism that permits unique identification of a specific package that correlates to the data in this SPDX document. This identifier enables a recipient to determine if any file in the original package has been changed. If the SPDX document is to be included in a package, this value should not be calculated. The [SHA1][SHA-1] algorithm shall be used to provide the checksum by default. The metadata for the package checksum field is shown in Table 22.
+Provide an independently reproducible mechanism that permits unique identification of a specific package in this SPDX document. If the SPDX document is to be included in the package, the `PackageVerificationCode` field should be used instead. The metadata for the package checksum field is shown in Table 22. For more specific use cases and examples of how to apply the package checksum field, see [Annex K.3 Verifying SPDX Packages](how-to-use.md#k3-verifying-spdx-packages).
 
 **Table 22 — Metadata for the package checksum field**
 
@@ -708,7 +708,7 @@ Provide an independently reproducible mechanism that permits unique identificati
 
 ### 7.10.2 Intent
 
-Eliminate confusion over which version or modification of a specific package the SPDX document references by providing a unique identifier of the package.
+Identify, based on the binary blob, which version or modification of a specific package the SPDX document references. This identifier enables a recipient to determine if any bits in the original package have been changed but does not specify which bits.
 
 ### 7.10.3 Examples