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 documents provide a reference allowing the identification of underlying software components present in a binary software package. However, linking specific Executable and Linking Format 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.

TODO: Improve the above paragraph to explain more about why people want this.

The ELF .reference note

The .reference note is an SHT_NOTE typed section, with the assigned section name .reference featuring an optional name and required descriptor.

SHT_NOTE sections are described on page 2-4 of the ELF specification, 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, including the naming requirements in its section 4.2.

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, 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

A minimum set of well-known types are proposed for 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.

Other media types may be used, provided they meet the naming requirements of RFC 6838.

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 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.

References