From 6e8b3bcae16c8e9bc4860249dddb66398795ce27 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 13 Dec 2017 14:01:00 -0800 Subject: [PATCH] chapters/3: Explicit external-reference ABNF This section has never been particularly tight. For example, the old: `` is an [idstring] that is defined in Appendix. was probably intended to reference the old Appendix VII (removed by the previous commit). This commit ties them strictly to generic URIs (see discussion in [1]). That breaks compatibility with the old form, but since the old form was unclear, I think that's ok. The cpe entries are already URIs in their own right, although they aren't registered with IANA [2]. You can resolve them via [3] (e.g. [4]). There are also other currently-unregistered schemes for referencing packages, e.g. [5]. But managing all of that complexity isn't something that SPDX should handle. Instead, folks interested in providing stable packaging and security references should work on registering their URIs with IANA (or on establishing them in the SPDX ecosystem despite their not being registered). This commit also tightens the relationship between category values and their rdf:resource URIs. And it removes "OTHER" and instead encourages authors to define their own category name (and associated rdf:resource URI). [1]: https://github.com/spdx/spdx-spec/issues/53 [2]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml [3]: https://nvd.nist.gov/products/cpe/search [4]: https://nvd.nist.gov/vuln/search/results?adv_search=true&cpe=cpe%3A2.3%3Aa%3Apivotal_software%3Aspring_framework%3A4.1.0%3A%2A%3A%2A%3A%2A%3A%2A%3A%2A%3A%2A%3A%2A [5]: https://github.com/package-url/purl-spec --- chapters/3-package-information.md | 72 +++++++++++++++++-------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/chapters/3-package-information.md b/chapters/3-package-information.md index c6a3bad6af..3c37addd76 100644 --- a/chapters/3-package-information.md +++ b/chapters/3-package-information.md @@ -946,56 +946,58 @@ Example: **3.21.3** Cardinality: Optional (one or many) -**3.21.4** Data Format: ` ` +**3.21.4** Data Format: ` ` -where: +In Tag:value format, values must match the following [ABNF][rfc5234]. +`URI` is from RFC 3986][rfc3986-s3]. +`space` is from [Appendi IV](appendix-IV-SPDX-license-expressions.md#overview). + +``` +external-reference = external-reference-category space URI +external-reference-category = 1*(ALPHA / DIGIT / "-" / "_") +``` + +`external-reference-category` values are case-sensitive. -`` is “SECURITY” | “PACKAGE-MANAGER” | “OTHER” +The following `external-reference-category` values are defined by this specification: -`` is an [idstring] that is defined in Appendix. +* `SECURITY`: References that help find security issues with the package (e.g. [common vulnerabilities and exposures (CVE)][cve]). +* `PACKAGE-MANAGER`: References that help install the package via a package manager (e.g. with [Apache Maven][maven]). -`` is the unique string with no spaces necessary to access the package-specific information, metadata, or content within the target location. The format of the locator is subject to constraints defined by the ``. +SPDX authors can use additional category values as they see fit, although they should define the category using [an external reference comment](#3.22). +Authors are encouraged to submit these additional categories to this specification for standardization. **3.21.5** Tag: `ExternalRef:` Example: - ExternalRef: SECURITY cpe23Type cpe:2.3:a:pivotal_software:spring_framework:4.1.0:*:*:*:*:*:*:* + ExternalRef: SECURITY cpe:2.3:a:pivotal_software:spring_framework:4.1.0:*:*:*:*:*:*:* - ExternalRef: OTHER LocationRef-acmeforge acmecorp/acmenator/4.1.3-alpha + ExternalRef: PACKAGE-MANAGER https://repo1.maven.org/maven2/org/apache/commons/commons-text/1.2/ -**3.21.6** RDF: property `target` in class `spdx:ExternalRef` +**3.21.6** XML: `spdx:ExternalRef` -Example (for a ‘listed’ location): +External references can be expressed in XML via an `` element, with `` and `` child elements. - - ... - - - - - org.apache.commons:commons-lang:3.2.1 - - - ... - +The `external-reference-category` values from [section 3.21.4](#3.21.4) map to `rdf:resource` values with the pattern: -Example (for a not ‘listed’ location): + http://spdx.org/rdf/terms#referenceCategory_{external-reference-category} - +Categories which are not defined in this specification should not use URIs with an `spdx.org` authority. + +For example: + + ... - - - acmecorp/acmenator/4.1.3-alpha + + https://repo1.maven.org/maven2/org/apache/commons/commons-text/1.2/ ... -The referenceType value for a non-listed location consists of the SPDX document namespace (per [section 2.5](2-document-creation-information.md#2.5)) followed by a “#” and the category as defined in 3.21.4. - ## 3.22 External Reference Comment **3.22.1** Purpose: To provide human-readable information about the purpose and target of the reference. @@ -1018,21 +1020,25 @@ Example: security vulnerabilities (CVEs) which affect Vendor Product Version acmecorp:acmenator:6.6.6. -**3.22.6** RDF: Property `rdfs:comment` in class `spdx:ExternalRef` +**3.22.6** XML: `rdfs:comment` in class `spdx:ExternalRef` ... - - - org.apache.commons:commons-lang:3.2.1 + + cpe:2.3:a:pivotal_software:spring_framework:4.1.0:*:*:*:*:*:*:* NIST National Vulnerability Database (NVD) describes security vulnerabilities (CVEs) which affect Vendor Product Version - acmecorp:acmenator:6.6.6 + pivotal_software:spring_framework:4.1.0. ... - \ No newline at end of file + + +[cve]: https://cve.mitre.org/ +[maven]: https://maven.apache.org/ +[rfc3986-s3]: https://tools.ietf.org/html/rfc3986#section-3 +[rfc5234]: https://tools.ietf.org/html/rfc5234