Adoptium® Marketplace Publisher Produktlisting-Repository

Übersicht

Adoptium bewirbt Produkte, die im Marketplace gelistet sind. Jeder Herausgeber verwaltet einen Speicherort mit strukturierten Informationen über seine Produkte. Adoptium aktualisiert den Marketplace regelmäßig mit den Informationen aus Ihrem Produktlisting. Der Speicherort verweist auf ein „Repository" von Datenressourcen. Ein solches Repository kann als einfaches Dateisystem, dynamisch erstellter Datenstrom, versionskontrollierter Speicher, Datenbank oder eine andere Einrichtung implementiert werden, die auf HTTP-Anfragen für einzelne URIs mit den unten beschriebenen Informationen antwortet.

In den nachfolgenden Beschreibungen und Beispielen verwenden wir die Begriffe „Dateien" und „Verzeichnisse" als Implementierung des Repositorys, um es einfach zu halten.

Nomenklatur

Ein Repository besteht aus drei Dateitypen: Index-Dateien, Release-Dateien und Signatur-Dateien.

Indexdateien: beschreiben den Speicherort von Release-Dateien und Indexdateien.
Release-Dateien: enthalten eine Liste von Marketplace-Produkten.
Signaturdateien: enthalten eine digitale Signatur, die einer Index- oder Release-Datei zugeordnet ist.

Alle Dateien werden unter der Annahme einer UTF-8-Kodierung gelesen.

Signaturdateien

Signaturdateien werden verwendet, um sicherzustellen, dass die Index- und Release-Dateidaten korrekt empfangen wurden und auf dem Weg nicht verändert wurden. Der Adoptium-Marketplace-Agent liest eine Datei und überprüft die zugehörige Dateisignatur. Die Signatur der Datei wird in einer Datei mit demselben Namen wie die signierte Datei gespeichert, mit dem Suffix .sha256.sign.

Die Signatur muss ein Base64-kodierter, RSA-verschlüsselter SHA-256-Hash Ihres gesamten Dateiinhalts sein. Die Signatur wird mit dem öffentlichen Schlüssel verifiziert, der in Ihren Herausgeberinformationen angegeben ist.

Es gibt eine Reihe von Tools und Codebeispielen, die bei der Erstellung solcher Signaturen helfen.

Generierung, Verifizierung und Kodierung einer Signatur mit OpenSSL

# Generate signature
openssl dgst -sha256 -sign private.pem -out index.json.sig index.json

# Verify
openssl dgst -sha256 -verify public.pem -signature index.json.sig index.json

#Base64 encode for publishing
cat index.json.sig | base64 -w 0 > index.json.sha256.sign

Einfaches Produktlisting-Repository

Das einfachste Produktlisting-Repository umfasst eine Indexdatei und eine Release-Datei mit zugehörigen digitalen Signaturen.

Die oberste Indexdatei muss sich im Stammverzeichnis des Repository-Speicherorts befinden und muss index.json heißen.

Hier ein Beispiel für ein einfaches Listing-Repository.

Example 1. Einfaches Repository-Layout

/index.json (1)
/index.json.sha256.sign (2)
/release.json (3)
/release.json.sha256.sign (4)

1	Haupt-Produktrepository-Indexdatei.
2	Digitale Signatur für die Indexdatei.
3	Produkt-Release-Listing-Datei.
4	Digitale Signatur für die Release-Listing-Datei.

Die einfachste index.json-Datei enthält nur einen Verweis auf eine einzelne releases.json-Datei.

{
  "schema_version": "1.0.0",
  "releases": [
    "example.json"
  ]
}

Strukturiertes Repository-Layout

Das Produktlisting-Repository kann mit mehreren Index- und Release-Dateien strukturiert werden, um den Veröffentlichungspräferenzen jedes Anbieters gerecht zu werden. Beispielsweise kann ein Herausgeber wählen, eine Release-Datei pro Java-Version, pro Plattform, pro Kalender-Release usw. zu erstellen. Der Adoptium-Marketplace beginnt bei der Stamm-index.json und durchläuft transitiv jede Indexdatei vollständig, um alle Release-Dateien zu finden.

Als weiteres komplexeres Beispiel zeigt das folgende Repository eine Release-Dateistruktur, die nach Java-Version und Release-Bezeichner organisiert ist.

Example 2. Strukturiertes Repository-Layout

.
├── 17
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk_17_0_1_12.json
│   ├── jdk_17_0_1_12.json.sha256.sign
│   ├── jdk_17_0_2_8.json
│   └── jdk_17_0_2_8.json.sha256.sign
├── 8
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk8u312_b07.json
│   └── jdk8u312_b07.json.sha256.sign
├── index.json
└── index.json.sha256.sign

In diesem Repository würde die Stamm-/index.json enthalten:

{
  "schema_version": "1.0.0",
  "indexes": [
    "8/index.json",
    "17/index.json"
  ],
  "releases": [
  ]
}

und die 17/index.json würde enthalten:

{
  "schema_version": "1.0.0",
  "indexes": [
  ],
  "releases": [
    "jdk_17_0_1_12.json",
    "jdk_17_0_2_8.json"
  ]
}

Beachten Sie, dass obwohl wir in diesem Beispiel eine Indexdatei pro Java-Hauptversion und eine Release-Datei für jedes Java-Release erstellt haben, dies keine Anforderung ist. Eine Indexdatei kann mehrere Indizes und Releases enthalten, und eine Release-Datei kann bei Bedarf mehrere Versions-Releases enthalten.

Tip

Jeder Index- und Release-Datei-Verweis wird relativ zum Indexdateipfad betrachtet, d. h. wenn https://release.adoptium.net/repo/17/index.json ein Release von jdk_17_0_2_8.json enthält, wird der Pfad https://release.adoptium.net/repo/17/jdk_17_0_2_8.json untersucht.

Release-Datei

Die Release-Datei enthält Details zu Ihren Produkten, einschließlich der Java-Version, der Zielmaschinenarchitektur, des Download-Speicherorts, des Testergebnis-Speicherorts und mehr. Der Name der Release-Datei ist für den Adoptium-Marketplace nicht relevant, außer dass er von einer Indexdatei wie oben beschrieben referenziert wird.

Ihre Produkt-Release-Datei-Listings müssen dem Marketplace-Produkt-JSON-Schema entsprechen, und Adoptium stellt Beispiele und Code bereit, um die Erstellung von Produktlisting-Daten im korrekten Format zu unterstützen.

Die aktuellen Temurin-Release-Dateien sind in unserem öffentlichen Marketplace-Daten-Repository verfügbar und dienen als Beispiel für das Erwartete.

Repository-Lese- und Marketplace-Aktualisierungsprozess

Adoptium ruft die Produktlisting-Informationen in der Regel stündlich ab, obwohl dieser Zeitraum nicht garantiert ist und variieren kann. Adoptium kann Ihre HTTP-Antwort-https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control[Cache-Control-HTTP-Header^] wie max-age berücksichtigen, um die Häufigkeit des Abrufens des Produkt-Listings zu steuern. Im Gegenzug kann die Adoptium-Anfrage eine bedingte Anfrage für Ihre Listing-Datei mit Headern wie If-Modified-Since angeben, um die Arbeitslast zu reduzieren.

Eine Produktlisting-Datei wird abgelehnt, wenn sie nicht dem Schema entspricht oder die Signatur den Inhalt nicht erfolgreich verifiziert. Wir werden Sie kontaktieren, wenn die Listing-Datei diese Validierungsprüfungen wiederholt nicht besteht.

Bei erfolgreichem Lesen ersetzt die neuen Marketplace-Informationen alle zuvor für diesen Anbieter gespeicherten Informationen.

Zusammenfassend läuft der Aktualisierungsprozess wie folgt ab:

Der Updater ruft den Stammindex ab und verifiziert ihn anhand der Signatur.
Weitere Indizes, falls vorhanden, werden rekursiv aus dem Index extrahiert, bis alle Indizes gelesen und verifiziert wurden.
Die Speicherorte aller Release-Dateien werden aus allen Indizes extrahiert.
Jede Release-Datei wird abgerufen und anhand der entsprechenden Signatur validiert.
Release-Datei-Informationen werden analysiert und gemäß dem Schema validiert.
Alle Produktinformationen werden für diesen Anbieter im Marketplace ersetzt.