From 8c91e43e7a59177bdf0bcedeb1ee091cd199e05d Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Sat, 13 Aug 2022 14:59:06 +0000 Subject: [PATCH] specs: add ELF references draft --- content/specs/elf-references.md | 217 ++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 content/specs/elf-references.md diff --git a/content/specs/elf-references.md b/content/specs/elf-references.md new file mode 100644 index 0000000..5d283b5 --- /dev/null +++ b/content/specs/elf-references.md @@ -0,0 +1,217 @@ +--- +title: "Embeddable URI references for ELF binaries" +--- + +*This specification is a work in progress, and has not been +submitted to any standards body for peer review. Do not use +this specification in any production capacity.* + +## Abstract + +*This section is non-normative.* + +Identifying the provenance of binary software components is +an important topic in the software servicing lifecycle with +numerous use-cases. [Software Bill of Materials][sbom] +documents provide a reference allowing the identification of +underlying software components present in a binary software +package. However, linking specific [Executable and Linking Format][elf] +binary objects in a software package to an SBOM document +varies depending on how the software package is built and +distributed. + +ELF references provide typed URIs which can be embedded in +ELF binaries as `SHT_NOTE` sections, providing the ability +to have an embedded copy of, or pointer to, any resource +including an SBOM document, allowing for universal +correlation between ELF binaries and their SBOM. + +## The ELF `.reference` note + +The `.reference` note is an `SHT_NOTE` typed section, with +the assigned section name `.reference`, with two sections. + +`SHT_NOTE` sections are described on page 2-4 of the [ELF +specification][elf], and the `.reference` note follows +this description. + +### The `.reference` name section + +The `namesz` and `name` fields are used to describe the +reference type. The type of the reference is optional +and *may* be omitted. If the type of the reference is +provided, then it *must* comply with [RFC 6838][rfc6838], +including the [naming requirements in its section 4.2][rfc6838-naming]. + +The `namesz` field *must* be set to `0` if the `.reference` +note does not have a type, otherwise it *must* be set to +the length of the typed URI in bytes with padding to ensure +4-byte alignment. + +Any padding bytes present as part of the `name` field *must* +be set to `NUL` (`0x0`). + +### The `.reference` descriptor section + +The `descsz` and `desc` fields are used for the reference +URI in the `.reference` note, which *must* be present. + +The `descsz` field *must* be set to the length of the +reference URI with padding to ensure 4-byte alignment. + +Any padding bytes present as part of the `desc` field *must* +be set to `NUL` (`0x0`). + +### Multiple `.reference` sections are allowed + +There may be multiple `.reference` note sections in an ELF +object per the [ELF specification][elf], page 1-15: + +> The object file format lets one define sections not in the +> list above. An object file may have more than one section +> with the same name. + +## Well-known types of `.reference` sections + +*This section is non-normative.* + +This spec proposes a minimum set of well-known types to use +as typed URIs in `.reference` sections: + +- Media Type: `text/spdx` + + Purpose: The `.reference` section defines a reference to an + SPDX document in tagged-value format. + +- Media Type: `application/spdx+json` + + Purpose: The `.reference` section defines a reference to an + SPDX document in JSON format, such as an SPDX 2.2 JSON document. + +- Media Type: `application/ld+json; profile="http://spdx.org/rdf/types"` + + Purpose: The `.reference` section defines a reference to an + SPDX document in JSON-LD format, such as an SPDX 3.0 document. + +- Media Type: `application/vnd.cyclonedx+json` + + Purpose: The `.reference` section defines a reference to a + CycloneDX document in JSON format. + +- Media Type: `application/vnd.cyclonedx+xml` + + Purpose: The `.reference` section defines a reference to a + CycloneDX document in XML format. + +- Media Type: `application/x.vnd.purl` + + Purpose: The `.reference` section defines a [package URL][purl]. + +Other media types *may* be used, provided they meet the [naming +requirements of RFC 6838][rfc6838-naming]. + +## Examples + +*This section is non-normative.* + +### Using `data:` URIs to embed text data + +*This section is non-normative.* + +This example embeds the text `Hello world!` as a `data:` URI +inside a `.reference` section: + +``` +{ + namesz: 12, + descsz: 56, + type: 1, + name: "text/plain\0\0", + desc: "data:text/plain;charset=utf-8;base64,SGVsbG8gd29ybGQh\0\0\0" +} +``` + +### Referencing an SPDX SBOM document + +*This section is non-normative.* + +This example embeds `https://example.org/sbom.spdx` as a +`.reference` section: + +``` +{ + namesz: 12, + descsz: 32, + type: 1, + name: "text/spdx\0\0\0", + desc: "https://example.org/sbom.spdx\0\0\0" +} +``` + +### Referencing a CycloneDX SBOM document + +*This section is non-normative.* + +This example embeds `https://example.org/sbom.cdx.json` as a +`.reference` section: + +``` +{ + namesz: 32, + descsz: 36, + type: 1, + name: "application/vnd.cyclonedx+json\0\0", + desc: "https://example.org/sbom.cdx.json\0\0\0" +} +``` + +### Referencing a Package URL + +*This section is non-normative.* + +This example embeds `pkg:apk/alpine/nano@6.3-r0?arch=x86_64` +as a `.reference` section: + +``` +{ + namesz: 24, + descsz: 40, + type: 1, + name: "application/x.vnd.purl\0\0", + desc: "pkg:apk/alpine/nano@6.3-r0?arch=x86_64\0\0" +} +``` + +## Acknowledgements + +*This section is non-normative.* + +The author of this specification wishes to express her +gratitude to [Laurent Bercot][skarnet] for reviewing the +initial concept. While that concept did not emerge unscathed +from his review, the specification that resulted is both more +composable and generic as a result. + + [skarnet]: https://www.skarnet.org/ + +## References + +* [Software Bill of Materials][sbom] specification as written + by CISA. + + [sbom]: https://www.cisa.gov/sbom + +* [Executable and Linking Format][elf] specification as written + by the TIS Committee. + + [elf]: https://refspecs.linuxfoundation.org/elf/elf.pdf + +* [RFC 6838][rfc6838] specification as published by the IETF, + ISSN 2070-1721. + + [rfc6838]: https://www.rfc-editor.org/rfc/rfc6838 + [rfc6838-naming]: https://www.rfc-editor.org/rfc/rfc6838#section-4.2 + +* [Package URL][purl] specification. + + [purl]: https://github.com/package-url/purl-spec