Adoptium® マーケットプレイスパブリッシャー製品リスティングリポジトリ

概要

Adoptium はマーケットプレイスに掲載された製品をプロモーションします。各パブリッシャーは製品に関する構造化された情報を含む場所を管理します。Adoptium は定期的に製品リスティングの情報でマーケットプレイスを更新します。この場所はデータリソースの「リポジトリ」を指します。このようなリポジトリは、シンプルなファイルシステム、動的に生成されるデータストリーム、バージョン管理されたストア、データベース、または HTTP リクエストに対して以下に説明する情報を返すその他の仕組みとして実装できます。

以下の説明と例では、シンプルに説明するためにリポジトリの実装として「ファイル」と「ディレクトリ」という用語を使用します。

用語

リポジトリは、*インデックス*ファイル、*リリース*ファイル、*署名*ファイルの3種類のファイルで構成されます。

インデックスファイル：リリースファイルおよびインデックスファイルの場所を記述します。
リリースファイル：マーケットプレイス製品のリストを含みます。
署名ファイル：インデックスまたはリリースファイルに関連するデジタル署名を含みます。

すべてのファイルは UTF-8 エンコーディングで読み込まれます。

署名ファイル

署名ファイルは、インデックスおよびリリースファイルのデータが正しく受信され、転送中に改ざんされていないことを確認するために使用されます。Adoptium マーケットプレイスエージェントはファイルを読み込み、関連するファイルの署名を確認します。ファイルの署名は、署名対象のファイルと同じ名前に .sha256.sign サフィックスを付けたファイルに格納されます。

署名は、ファイルコンテンツ全体の Base64 エンコードされた RSA 暗号化 SHA-256 ハッシュでなければなりません。署名はパブリッシャー情報で提供された公開鍵を使用して検証されます。

このような署名を生成するためのツールやツールおよびコード例が多数利用可能です。

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

シンプルな製品リスティングリポジトリ

最もシンプルな製品リスティングリポジトリは、1つのインデックスファイルと1つのリリースファイル、およびそれぞれのデジタル署名で構成されます。

トップレベルのインデックスファイルはリポジトリの場所のルートに配置し、index.json という名前にする必要があります。

シンプルなリスティングリポジトリの例を以下に示します。

Example 1. シンプルなリポジトリレイアウト

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

1	メイン製品リポジトリのインデックスファイル。
2	インデックスファイルのデジタル署名。
3	製品リリースリスティングファイル。
4	リリースリスティングファイルのデジタル署名。

最もシンプルな index.json ファイルは、単一の releases.json ファイルへの参照のみを含みます。

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

構造化されたリポジトリレイアウト

製品リスティングリポジトリは、各ベンダーの公開設定に合わせて複数のインデックスファイルとリリースファイルで構成することができます。たとえば、Java バージョンごと、プラットフォームごと、カレンダーリリースごとなどにリリースファイルを生成することができます。Adoptium マーケットプレイスはルートの index.json から始まり、すべてのリリースファイルを見つけるために各インデックスファイルを再帰的に網羅的に検索します。

さらに複雑な例として、次のリポジトリは Java バージョンとリリース識別子で整理されたリリースファイル構造を示しています。

Example 2. 構造化されたリポジトリレイアウト

.
├── 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

このリポジトリでは、ルートの /index.json は次の内容になります。

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

そして 17/index.json は次の内容になります。

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

この例では Java のメジャーバージョンごとに1つのインデックスファイルを作成し、Java リリースごとに1つのリリースファイルを作成していますが、これは必須ではありません。インデックスに複数のインデックスとリリースを含めることができ、リリースファイルに複数のバージョンリリースを含めることもできます。

Tip

各インデックスおよびリリースファイルの参照はインデックスファイルパスからの相対パスとして扱われます。つまり、https://release.adoptium.net/repo/17/index.json に jdk_17_0_2_8.json というリリースが含まれている場合、https://release.adoptium.net/repo/17/jdk_17_0_2_8.json のパスが検索されます。

リリースファイル

リリースファイルには、Java バージョン、ターゲットマシンアーキテクチャ、ダウンロード場所、テスト結果の場所など、製品に関する詳細が含まれます。リリースファイルの名前は、上記のインデックスファイルから参照される以外、Adoptium マーケットプレイスには関係ありません。

製品のリリースファイルリスティングはマーケットプレイス製品 JSON スキーマに準拠する必要があり、Adoptium は正しい形式で製品リスティングデータを作成するためのサンプルおよびコードを提供しています。

実際の Temurin リリースファイルは公開されているマーケットプレイスデータリポジトリで確認でき、期待されるものの例として参照できます。

リポジトリの読み込みとマーケットプレイスの更新プロセス

Adoptium は通常1時間ごとに製品リスティング情報を取得しますが、この間隔は保証されておらず変動する場合があります。Adoptium は取得頻度のガイドとして、max-age などの HTTP レスポンスの cache-control HTTPヘッダーを考慮することがあります。また Adoptium のリクエストは、作業負荷を軽減するために If-Modified-Since などのヘッダーを使ったリスティングファイルへの条件付きリクエストを指定する場合があります。

製品リスティングファイルがスキーマに準拠していない場合、またはシグネチャがコンテンツの検証に成功しない場合は拒否されます。リスティングファイルがこれらの検証チェックに繰り返し失敗している場合はご連絡します。

正常に読み込まれると、新しいマーケットプレイス情報はこのベンダーに対して保持されている以前の情報を置き換えます。

まとめると、更新プロセスは次のように進みます：

アップデーターがルートインデックスを取得し、署名と照合して検証します。
さらにインデックスがある場合は、すべてのインデックスが読み込まれ検証されるまで再帰的に取得されます。
すべてのインデックスからすべてのリリースファイルの場所が抽出されます。
各リリースファイルが取得され、対応する署名と照合して検証されます。
リリースファイルの情報がスキーマに従って解析・検証されます。
このベンダーのすべての製品情報がマーケットプレイスで置き換えられます。

Adoptium® マーケットプレイス パブリッシャー製品リスティングリポジトリ

概要

用語