specs: add ELF references draft
ci/woodpecker/push/woodpecker Pipeline was successful
Details
ci/woodpecker/push/woodpecker Pipeline was successful
Details
parent
db89f9a5ae
commit
8c91e43e7a
|
|
@ -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
|
||||
Loading…
Reference in New Issue