Version: Digest mit Stückliste und Signatur

Was gebaut ist

Eine Version ist das, was HERMES ausliefert und was ein Ort startet. Dieser geplante Vertrag legt fest, woraus sie besteht und wie man ihr vertraut: ein Digest als Name, eine Stückliste als Inhalt, eine Signatur als Urheber und Auflagen als Bedingung, unter der sie laufen darf.

Ein geplanter Vertrag, kein erreichbarer Endpunkt

Die Felder beschreiben die vorgesehene Form einer Version. Sie folgt dem Aufbau eines OCI-Images mit Anlagen. Eine ausgelieferte Version, ein Register der Versionen und eine Schnittstelle dafür bestehen noch nicht.

Der Digest ist der Name

Eine Version heißt sha256: gefolgt vom Prüfwert ihres Manifests. Das Manifest nennt die Digests von Konfiguration und Schichten, und damit umfasst der Digest das ganze Image. Bezeichnungen wie eine Versionsnummer oder latest sind Namen, die auf einen Digest zeigen und morgen auf einen anderen zeigen können. Freigaben, Kanäle, Wellen und Verlauf nennen darum immer den Digest.

Stückliste, Herkunft, Signatur

An den Digest sind drei Anlagen gebunden. Die Stückliste nennt jede Komponente mit Name, Version, Lizenz und Package URL im Format SPDX oder CycloneDX. Die Herkunftsangabe nennt Quelle, Commit, Bauumgebung und Schritte des Baus. Die Signatur bestätigt den Digest des Manifests und liegt neben dem Image. Anlagen, die nicht an den Digest gebunden sind, gelten nicht.

Auflagen gehören zur Version

Begriff · Umgebung

Ein Ort, an dem eine Version läuft, mit Eigenschaften, einem Kanal und einem Stand, mit oder ohne Verbindung nach außen.

Umgebung im Zusammenhang

Die Auflagen nennen Plattformen, Mindestversion der Laufzeit, Ressourcen, erlaubte Vorgängerversionen, Zulassungen und Markierungen der Daten. HERMES gleicht sie mit den Eigenschaften der Umgebungen ab, bevor es ein Soll schreibt. Auch sie hängen signiert am Digest.

Geprüft vor dem Start

Begriff · Herkunft

Die Angabe zu einem Wert, aus welcher Quelle, welchem Objekt der Quelle und welchem Lauf er stammt. Herkunft belegt nicht, dass der Wert stimmt.

Herkunft im Zusammenhang

Ein Ort startet eine Version nur, wenn Signatur, Digest und Herkunft gegen die Regel des Orts bestehen: welche Schlüssel oder Identitäten signieren dürfen, welche Quellen und Bauumgebungen erlaubt sind. Die Prüfung läuft am Ort und braucht keine Verbindung zum Hersteller. Eine Version ohne gültige Signatur startet nicht.

Schema

{
  "digest": "sha256:<wert>",
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [{ "platform": { "architecture": "<architektur>", "os": "<system>" }, "digest": "sha256:<wert>" }],
  "attachments": {
    "sbom": { "format": "spdx | cyclonedx", "digest": "sha256:<wert>" },
    "provenance": { "digest": "sha256:<wert>" },
    "signature": { "digest": "sha256:<wert>" },
    "requirements": { "digest": "sha256:<wert>" }
  },
  "channel": "<kanal>"
}

Schema 1JSON · Schema mit Platzhaltern

Felder

Feld	Typ	Pflicht	Bedeutung
`digest`	`string`	ja	sha256: und Prüfwert des Manifests. Der Name der Version.
`mediaType`	`string`	ja	Art des Manifests, für mehrere Plattformen ein Image Index.
`manifests`	`object[]`	ja	Je Plattform ein Manifest mit Architektur, Betriebssystem und Digest.
`attachments.sbom`	`object`	ja	Stückliste in SPDX oder CycloneDX, an den Digest gebunden.
`attachments.provenance`	`object`	ja	Herkunft des Baus: Quelle, Commit, Bauumgebung, Schritte.
`attachments.signature`	`object`	ja	Signatur über den Digest des Manifests.
`attachments.requirements`	`object`	ja	Auflagen: Plattformen, Laufzeit, Ressourcen, Vorversionen, Zulassungen, Markierungen.
`attachments.vex`	`object`	nein	Aussagen zur Ausnutzbarkeit bekannter Schwachstellen, von Menschen verantwortet.
`channel`	`string`	nein	Kanal, in dem der Digest steht. Der Kanal zeigt auf den Digest, nicht umgekehrt.

Fehlerfälle

Kennung	Bedeutung
`VERSION_SIGNATURE_INVALID`	Die Signatur fehlt oder passt nicht zum Digest und zu einer erlaubten Identität.
`VERSION_PROVENANCE_REJECTED`	Quelle oder Bauumgebung sind nach der Regel des Orts nicht erlaubt.
`VERSION_REQUIREMENTS_UNMET`	Eine Auflage der Version wird von der Umgebung nicht erfüllt.
`VERSION_ATTACHMENT_MISSING`	Eine verlangte Anlage fehlt oder ist nicht an den Digest gebunden.
`VERSION_ROLLBACK_BLOCKED`	Der Wechsel auf den früheren Digest ist nach den Auflagen nicht erlaubt.

Grenze

Grenze: Dieser Schnittstellenvertrag ist geplant. Er belegt weder eine ausgelieferte Version noch ein Register. Die Stückliste nennt, was im Image steht, und sagt nichts darüber, ob es sicher ist.

Quellen

OCI Image Format SpecificationOpen Container Initiative. Manifest, Konfiguration, Schichten und Image Index.
SPDX SpecificationLinux Foundation. Format der Software-Stückliste, auch als ISO/IEC 5962.
CycloneDX SpecificationOWASP. Zweites verbreitetes Format der Stückliste.
SLSA: Supply-chain Levels for Software ArtifactsBeschreibung der Herkunft eines Baus.

Eine Version ist ein Digest mit Stückliste und Signatur.