docs/ELF_PACKAGE_METADATA.md

   1 ---
   2 title: Package Metadata for ELF Files
   3 category: Interfaces
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Package Metadata for Core Files
   9
  10 *Intended audience: hackers working on userspace subsystems that create ELF binaries
  11 or parse ELF core files.*
  12
  13 ## Motivation
  14
  15 ELF binaries get stamped with a unique, build-time generated hex string identifier called
  16 `build-id`, [which gets embedded as an ELF note called `.note.gnu.build-id`](https://fedoraproject.org/wiki/Releases/FeatureBuildId).
  17 In most cases, this allows to associate a stripped binary with its debugging information.
  18 It is used, for example, to dynamically fetch DWARF symbols from a debuginfo server, or
  19 to query the local package manager and find out the package metadata or, again, the DWARF
  20 symbols or program sources.
  21
  22 However, this usage of the `build-id` requires either local metadata, usually set up by
  23 the package manager, or access to a remote server over the network. Both of those might
  24 be unavailable or forbidden.
  25
  26 Thus it becomes desirable to add additional metadata to a binary at build time, so that
  27 `systemd-coredump` and other services analyzing core files are able to extract said
  28 metadata simply from the core file itself, without external dependencies.
  29
  30 ## Implementation
  31
  32 This document will attempt to define a common metadata format specification, so that
  33 multiple implementers might use it when building packages, or core file analyzers, and
  34 so on.
  35
  36 The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded,
  37 read-only ELF header section, in a name-value JSON object format. Implementers working on parsing
  38 core files should not assume a specific list of names, but parse anything that is included
  39 in the section, and should look for the note using the `note type`. Implementers working on
  40 build tools should strive to use the same names, for consistency. The most common will be
  41 listed here. When corresponding to the content of os-release, the values should match, again for consistency.
  42
  43 If available, the metadata should also include the debuginfod server URL that can provide
  44 the original executable, debuginfo and sources, to further facilitate debugging.
  45
  46 * Section header
  47
  48 ```
  49 SECTION: `.note.package`
  50 note type: `0xcafe1a7e`
  51 Owner: `FDO` (FreeDesktop.org)
  52 Value: a single JSON object encoded as a zero-terminated UTF-8 string
  53 ```
  54
  55 * JSON payload
  56
  57 ```json
  58 {
  59      "type":"rpm",          # this provides a namespace for the package+package-version fields
  60      "os":"fedora",
  61      "osVersion":"33",
  62      "name":"coreutils",
  63      "version":"4711.0815.fc13",
  64      "architecture":"arm32",
  65      "osCpe": "cpe:/o:fedoraproject:fedora:33",          # A CPE name for the operating system, `CPE_NAME` from os-release is a good default
  66      "debugInfoUrl": "https://debuginfod.fedoraproject.org/"
  67 }
  68 ```
  69
  70 The format is a single JSON object, encoded as a zero-terminated `UTF-8` string.
  71 Each name in the object shall be unique as per recommendations of
  72 [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Strings shall
  73 not contain any control character, nor use `\uXXX` escaping.
  74
  75 When it comes to JSON numbers, this specification assumes that JSON parsers
  76 processing this information are capable of reproducing the full signed 53bit
  77 integer range (i.e. -2⁵³+1…+2⁵³-1) as well as the full 64-bit IEEE floating
  78 point number range losslessly (with the exception of NaN/-inf/+inf, since JSON
  79 cannot encode that), as per recommendations of
  80 [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#page-8). Fields in
  81 these JSON objects are thus permitted to encode numeric values from these
  82 ranges as JSON numbers, and should not use numeric values not covered by these
  83 types and ranges.
  84
  85 Reference implementations of [packaging tools for .deb and .rpm](https://github.com/systemd/package-notes)
  86 are available, and provide macros/helpers to include the note in binaries built
  87 by the package build system. They make use of the new `--package-metadata` flag that
  88 is available in the bfd, gold, mold and lld linkers (versions 2.39, 1.3.0 and 15.0
  89 respectively). This linker flag takes a JSON payload as parameter.
  90
  91 ## Well-known keys
  92
  93 The metadata format is intentionally left open, so that vendors can add their own information.
  94 A set of well-known keys is defined here, and hopefully shared among all vendors.
  95
  96 | Key name     | Key description                                                          | Example value                         |
  97 |--------------|--------------------------------------------------------------------------|---------------------------------------|
  98 | type         | The packaging type                                                       | rpm                                   |
  99 | os           | The OS name, typically corresponding to ID in os-release                 | fedora                                |
 100 | osVersion    | The OS version, typically corresponding to VERSION_ID in os-release      | 33                                    |
 101 | name         | The source package name                                                  | coreutils                             |
 102 | version      | The source package version                                               | 4711.0815.fc13                        |
 103 | architecture | The binary package architecture                                          | arm32                                 |
 104 | osCpe        | A CPE name for the OS, typically corresponding to CPE_NAME in os-release | cpe:/o:fedoraproject:fedora:33        |
 105 | debugInfoUrl | The debuginfod server url, if available                                  | https://debuginfod.fedoraproject.org/ |