From 8e3ff25d2d0cd9f52d5d526d5ea2988351d27163 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 16 Nov 2023 17:56:30 +0100 Subject: [PATCH 1/2] ddi-spec: minor modernizations --- specs/discoverable_disk_image.md | 12 ++++++------ specs/extension_image.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/specs/discoverable_disk_image.md b/specs/discoverable_disk_image.md index 0bd91867..3bb1034f 100644 --- a/specs/discoverable_disk_image.md +++ b/specs/discoverable_disk_image.md @@ -7,15 +7,15 @@ SPDX-License-Identifier: CC-BY-4.0 --- # Discoverable Disk Image (DDI) -DDIs (Discoverable Disk Images) are self-describing file system images that follow the DPS -([Discoverable Partitions Specification](discoverable_partitions_specification.md)), wrapped in a GPT -partition table, that may contain root (or `/usr/`) filesystems, system extensions, configuration extensions, -portable services, containers and more, and are all protected by signed dm-verity all combined into one. -They are designed to be composable and stackable, and provide security by default. +DDIs (Discoverable Disk Images) are self-describing file system images that follow the DPS ([Discoverable +Partitions Specification](discoverable_partitions_specification.md)), wrapped in a GPT partition table, that +may contain root (or `/usr/`) filesystems for bootable OS images, system extensions, configuration +extensions, portable services, containers and more, and shall be protected by signed `dm-verity` all combined +into one. They are designed to be composable and stackable, and provide security by default. ## Image Format The images use the GPT partition table verbatim, so it will not be redefined here. Each partition contains -a standard Linux filesystem (e.g.: squashfs), so again this will not be redefined here. +a standard Linux filesystem (e.g.: `erofs`), so again this will not be redefined here. The [DPS](discoverable_partitions_specification.md) defines the GUIDs to use and the format of the dm-verity signature partition's JSON content. diff --git a/specs/extension_image.md b/specs/extension_image.md index afcbfd7b..2011d79e 100644 --- a/specs/extension_image.md +++ b/specs/extension_image.md @@ -64,7 +64,7 @@ Examples: `"SYSEXT_LEVEL=2"`, `"CONFEXT_LEVEL=15.14"`. If not present, and if `VERSION_ID=` is present instead, then this will be checked instead. -#### `VERSION_ID=` `ID=` `ARCHITECTURE=` +#### `VERSION_ID=`, `ID=`, `ARCHITECTURE=` `VERSION_ID=` and `ID=` are used to match the Extension Image with the root DDI, and `ARCHITECTURE=` is used to match with the host's CPU architecture, as defined in the [`os-release` specification](https://www.freedesktop.org/software/systemd/man/os-release.html). @@ -79,7 +79,7 @@ can be used to also identify the sysext itself, by prefixing them with `SYSEXT_` There are also extension-specific fields that do not apply to 'os-release', `SYSEXT_SCOPE=`, `CONFEXT_SCOPE=` and `ARCHITECTURE=`. -#### `SYSEXT_SCOPE=` `CONFEXT_SCOPE=` +#### `SYSEXT_SCOPE=`, `CONFEXT_SCOPE=` Takes a space-separated list of one or more of the strings `"system"`, `"initrd"` and `"portable"`. This field is optional and indicates what environments the system extension is applicable to: i.e. to regular systems, to initrds, or to [portable service images](https://systemd.io/PORTABLE_SERVICES/). If unspecified, From 68dd1d96c359908cf494454af2b0ce1b9d4f9599 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 16 Nov 2023 17:57:06 +0100 Subject: [PATCH 2/2] ddi-spec: document which suffix, mime type and sector sizes to use for DDIs --- specs/discoverable_disk_image.md | 16 +++++++++++++++- specs/extension_image.md | 5 +++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/specs/discoverable_disk_image.md b/specs/discoverable_disk_image.md index 3bb1034f..f4ac6d37 100644 --- a/specs/discoverable_disk_image.md +++ b/specs/discoverable_disk_image.md @@ -17,7 +17,21 @@ into one. They are designed to be composable and stackable, and provide securit The images use the GPT partition table verbatim, so it will not be redefined here. Each partition contains a standard Linux filesystem (e.g.: `erofs`), so again this will not be redefined here. The [DPS](discoverable_partitions_specification.md) defines the GUIDs to use and the format of the -dm-verity signature partition's JSON content. +`dm-verity` signature partition's JSON content. + +It is recommended to use a sector size of 512 bytes or 4096 for DDIs. Software operating with DDIs should +automatically derive the sector size used for a DDI by looking for the `EFI PART` magic string at offsets 512 +or 4096, as per GPT specification. + +## Naming + +DDIs should use `.raw` as file suffix. A secondary suffix may be used to clarify the specific usage class of +a DDI. For now the two secondary suffixes `.sysext.raw` and `.confext.raw` are defined (for system extension +DDIs and configuration extension DDIs, see [Extension +Images](https://uapi-group.org/specifications/specs/extension_image) for details). + +The MIME type for DDIs is `application/vnd.efi.img`, [as per +IANA](https://www.iana.org/assignments/media-types/application/vnd.efi.img). ## Image Version If the DDI is versioned, the version format described in the diff --git a/specs/extension_image.md b/specs/extension_image.md index 2011d79e..58ddd3af 100644 --- a/specs/extension_image.md +++ b/specs/extension_image.md @@ -38,6 +38,11 @@ to identify them. Extension Images should be additive, and not override content present in the base image or other DDIs, but this will not be enforced. +## File Suffix +Since extensions images are DDIs, they should carry the `.raw` suffix. In order to make discerning system +extensions and configuration extensions easy it is recommended to use the `.sysext.raw` suffix for system +extensions, and `.confext.raw` for configuration extensions. + ## Identification An Extension Image must contain a `extension-release.` file, where `` must either match the name of the sysext minus the suffix, or alternatively `extension-release.` must be tagged with a