Merge pull request #88 from poettering/ddi-suffix-mime

ddi-spec: define suggested suffixes, mime types, sector sizes for DDIs

Author: bluca

specs/discoverable_disk_image.md

@@ -7,17 +7,31 @@ 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.
+`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

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.<IMAGE>` file, where `<IMAGE>` must either match the
 name of the sysext minus the suffix, or alternatively `extension-release.<IMAGE>` must be tagged with a
@@ -64,7 +69,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 +84,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,