JAR ファイルの仕様

目次

はじめに

JAR ファイルは普及している ZIP ファイル形式に基づくファイル形式で、多数のファイルを 1 つにまとめるために使用されます。JAR ファイルは、基本的にはオプションの META-INF ディレクトリを格納する ZIP ファイルです。JAR ファイルは、コマンド行 jar ツールか、Java プラットフォームで java.util.jar API を使用して作成できます。JAR ファイルの名前には制約がないため、各プラットフォームで許可されているファイル名を使うことができます。

多くの場合、JAR ファイルは、単純な Java のクラスファイルまたはリソースのアーカイブではありません。JAR ファイルは、アプリケーションおよび拡張機能の構築ブロックとして使います。META-INF ディレクトリが存在する場合は、セキュリティー、バージョン管理、拡張機能、サービスなど、パッケージおよび拡張機能の構成データを格納するときに使います。

META-INF ディレクトリ

Java 2 プラットフォームでは、アプリケーション、拡張機能、クラスローダー、およびサービスが構成されるときに、META-INF ディレクトリから次のファイルとディレクトリの認識および解釈が行われます。 拡張機能およびパッケージ関連のデータの定義に使うマニフェストファイル。 このファイルは、jar ツールの新しいオプション「-i」によって生成されます。アプリケーションまたは拡張機能で定義されたパッケージの位置情報が格納されます。JarIndex 実装に組み込まれており、クラスのロード処理を速くするためにクラスローダーによって使われます。 JAR ファイルの署名ファイルです。 「x」は、ベースファイル名を表します。 同じベースファイル名を持つ署名ファイルに関連付けられた署名ブロックファイル。対応する署名ファイルのデジタル署名が格納されます。 このディレクトリには、サービスプロバイダ構成ファイルがすべて格納されます。

名前-値ペアおよびセクション

各構成ファイルの内容を詳細に設定する前に、形式の規則をいくつか定義する必要があります。ほとんどの場合、マニフェストファイルまたは署名ファイルに含まれる情報は、RFC822 の規定に従い、いわゆる「名前:値」ペアとして表現されます。 「名前:値」ペアは、ヘッダーまたは属性とも呼ばれます。

名前-値ペアのグループを「セクション」と呼びます。セクションはほかのセクションと空白行で分けられます。

バイナリデータは、どの形式であれ base64 で表されます。行の長さが 72 バイトを超えるようなバイナリデータについては継続が必要です。バイナリデータの例はダイジェストおよび署名です。

実装によっては、65535 バイトまでのヘッダー値がサポートされます。

このドキュメントの仕様には同一の文法が使われており、終端記号は固定幅のフォントで示され、終端以外の記号はイタリック書体で示されています。

仕様:

  section:                       *header +newline
  nonempty-section:     +header +newline
  newline:                     CR LF | LF | CR (not followed by LF)
  header:                      name :value
  name:                        alphanum *headerchar
  value:                         SPACE *otherchar newline *continuation
  continuation:             SPACE *otherchar newline
  alphanum:                 {A-Z} | {a-z} | {0-9}
  headerchar:               alphanum | - | _
  otherchar:                 any UTF-8 character except NUL, CR and LF

; Also:To prevent mangling of files sent via straight e-mail, no
; header will start with the four letters "From".
 

上の仕様で定義されている終端以外の記号は、以降の仕様で使われています。

JAR マニフェスト

概要

JAR ファイルマニフェストは、メインセクションと各 JAR ファイルエントリの複数の個別セクションで構成され、それぞれ改行文字で区切られています。メインセクションおよび個別セクションは、すでに説明したセクションの構文に準拠しています。各セクションには、固有の制約と規則があります。

メインセクションには、JAR ファイル自体のセキュリティーと構成情報以外に、その JAR ファイルが使われているアプリケーションまたは拡張機能のセキュリティーと構成情報を指定します。また、各マニフェストエントリに適用されるメイン属性も定義します。メインセクションの属性に、「Name」と同じ名前を付けることはできません。メインセクションは、空白行で終わります。

個別セクションには、この JAR ファイルに格納されているパッケージまたはファイルのさまざまな属性を定義します。アーカイブ内のすべてのファイルをマニフェストのエントリにリストする必要はありませんが、署名するすべてのファイルはリストする必要があります。マニフェストファイル自体はリストしないでください。各セクションは、「Name」という名前の属性で始まる必要があります。この属性の値は、ファイルを起点とした相対パス、またはアーカイブの外部のデータを参照する絶対 URL でなければなりません。

1 つのファイルエントリに複数の個別セクションがある場合は、これらのセクションの属性はマージされます。特定の属性の値がセクションによって異なる場合は、最後のセクションの値が認識されます。

理解できない属性は無視されます。アプリケーションによって使われる実装固有の情報に、理解できない属性が含まれていることがあります。

マニフェストの仕様:

  manifest-file:                    main-section newline *individual-section
  main-section:                   version-info newline *main-attribute
  version-info:                     Manifest-Version: version-number
  version-number :              digit+{.digit+}*
  main-attribute:                (any legitimate main attribute) newline
  individual-section:            Name : value newline *perentry-attribute
  perentry-attribute:           (any legitimate perentry attribute) newline
  newline :                           CR LF | LF | CR (not followed by LF)
   digit:                                {0-9} 

上の仕様では、メインセクションに指定した属性はメイン属性、個別セクションに指定した属性はエントリ別属性として参照されます。属性によっては、メインセクションと個別セクションの両方で指定できます。この場合、そのエントリでは、メイン属性の値はエントリ別属性の値によってオーバーライドされます。これら 2 つの属性は、次のように定義されます。
 

メイン属性

メイン属性は、マニフェストのメインセクションに指定されている属性です。メイン属性は、次のグループに分類されます。

エントリ別属性

エントリ別属性は、そのマニフェストエントリが関連付けられている個別の JAR ファイルエントリにだけ適用されます。メインセクションに同じ属性がある場合は、メイン属性の値はエントリ別属性の値によってオーバーライドされます。たとえば、JAR ファイル a.jar には、次のコンテンツがマニフェストに定義されています。 
Manifest-Version: 1.0
Created-By: 1.2 (Sun Microsystems Inc.)
Sealed: true
Name: foo/bar/
Sealed: false

この場合、foo.bar パッケージを除き、a.jar 内に保管されているパッケージがすべてシールされます。

エントリ別属性は、次のグループに分類されます。

署名付き JAR ファイル

概要

JAR ファイルに署名するには、コマンド行 jarsigner ツールを使うか、java.security API を直接使います。JAR ファイルを jarsigner ツールで署名した場合は、META-INF ディレクトリ内の署名に関係しないファイルを含め、すべてのファイルエントリが署名されます。署名に関係するファイルは次のとおりです。 署名に関係しないファイルが META-INF サブディレクトリ内にあっても、それらのファイルは署名に関係するファイルとは見なされません。上記のファイル名と大文字と小文字の区別が異なるファイル名は予約済みで、それらのファイルは署名されません。

JAR ファイルのサブセットを署名するには、java.security API を使用します。署名された JAR ファイルは、ファイルのマニフェストが更新されていることと META-INF ディレクトリに署名ファイルと署名ブロックファイルが追加されていることを除けば、元の JAR ファイルとまったく同じです。jarsigner を使用しない場合、署名プログラムは、署名ファイルと署名ブロックファイルの両方を構築する必要があります。

署名付き JAR ファイル内で署名されたすべてのファイルエントリについて、そのエントリがすでにマニフェスト内に存在していないかぎり、個別のマニフェストエントリが作成されます。各マニフェストエントリには、1 つまたは複数のダイジェスト属性とオプションの Magic 属性がリストされます。

署名ファイル

各署名者は、拡張子が .SF の署名ファイルによって表されます。このファイルの大部分は、マニフェストファイルと同じです。このファイルは、署名者から提供された情報の入ったメインセクションで構成されます。ただし、この情報は特定の jar ファイルエントリに固有のものではありません。メインセクションには、Signature-Version および Created-By 属性 (「メイン属性」を参照) に加えて、次のセキュリティー属性も含まれています。 メインセクションのあとには、個々のエントリのリストが続きます。それらのエントリの名前も、マニフェストファイル内に存在する必要があります。それぞれの個別エントリには、少なくともマニフェストファイル内の対応するエントリのダイジェストが含まれている必要があります。

マニフェストファイルに登場するが署名ファイルには登場しないパスまたは URL は、計算に使用されません。

署名の検証

JAR ファイルの検証が成功するのは、署名が有効であり、かつ署名の生成以後に JAR ファイル内のどのファイルも変更されていない場合です。JAR ファイルの検証は、次の手順で行われます。

  1. マニフェストがはじめて解析されるときに、署名を署名ファイルに対して検証します。効率化のために、この検証結果を記録しておくことができます。この検証では、実際のアーカイブファイルでなく、署名そのものだけが検証されます。

  2. 署名ファイルに 1 つの x-Digest-Manifest 属性が存在する場合は、マニフェスト全体から計算したダイジェストに照らして値を検証します。署名ファイルに複数の x-Digest-Manifest 属性が存在する場合は、そのうち少なくとも 1 つが計算したダイジェスト値と一致することを検証します。

  3. 署名ファイルに x-Digest-Manifest 属性が存在しないか、前の手順で計算したダイジェスト値がいずれも一致しない場合は、効率的に劣る方法で検証が行われます。

    1. 署名ファイルに 1 つの x-Digest-Manifest-Main-Attributes エントリが存在する場合は、マニフェストファイル内のメイン属性から計算したダイジェストに照らして値を検証します。この計算に失敗すると、JAR ファイルの検証が失敗します。この判断は、効率化のために記録しておくことができます。署名ファイルに x-Digest-Manifest-Main-Attributes エントリが存在しなくても、JAR ファイルの検証に影響はなく、マニフェストのメイン属性が検証されないだけです。

    2. 署名ファイルの各ソースファイル情報セクション内の値を、マニフェストファイルの対応するエントリから計算したダイジェスト値に照らして検証します。いずれのダイジェスト値も一致しない場合、JAR ファイルの検証が失敗します。

    x-Digest-Manifest 属性に格納されたマニフェストファイルのダイジェスト値が現在のマニフェストファイルのダイジェスト値と一致しない場合は、署名 (および署名ファイル) の生成後に (jar ツールを使用して) JAR ファイルに 1 つ以上のファイルが追加された可能性があります。jar ツールを使用してファイルを追加した場合、マニフェストファイルは (新しいファイル用のセクションが追加されて) 変更されますが、署名ファイルは変更されません。この場合、署名ファイルのヘッダー以外のセクションに格納されたダイジェスト値が、マニフェストファイル内の対応するセクションのダイジェスト値と一致するときは、署名の生成時に JAR ファイル内に存在していたファイルのうち、どのファイルも変更されていないことになり、検証は成功したものとして扱われます。

  4. マニフェスト内のエントリごとに、「Name:」属性から参照される実際のデータ (相対ファイルパスまたは URL) から計算されたダイジェストに照らして、マニフェストファイル内のダイジェスト値を検証します。いずれのダイジェスト値も一致しない場合、JAR ファイルの検証が失敗します。

マニフェストファイルの例:

Manifest-Version: 1.0
Created-By: 1.7.0 (Sun Microsystems Inc.)

Name: common/class1.class
SHA-256-Digest: (base64 representation of SHA-256 digest)

Name: common/class2.class
SHA1-Digest: (base64 representation of SHA1 digest)
SHA-256-Digest: (base64 representation of SHA-256 digest)
対応する署名ファイルは次のようになります。 
Signature-Version: 1.0
SHA-256-Digest-Manifest: (base64 representation of SHA-256 digest)
SHA-256-Digest-Manifest-Main-Attributes: (base64 representation of SHA-256 digest)

Name: common/class1.class
SHA-256-Digest: (base64 representation of SHA-256 digest)

Name: common/class2.class
SHA-256-Digest: (base64 representation of SHA-256 digest)

Magic 属性

特定のマニフェストエントリ上で署名を有効化するためにもう 1 つ必要なことは、そのエントリのマニフェストエントリ内の Magic キーペア値の値をベリファイアが理解することです。

Magic 属性はオプションですが、パーサーがそのエントリの署名を検証する場合は、エントリの Magic キーの値を理解する必要があります。

Magic 属性の値は、コンマで区切られたコンテキスト固有の文字列のセットです。コンマの前後の空白は無視されます。大文字小文字も無視されます。Magic 属性の正確な意味はアプリケーションによって異なります。これらの属性は、マニフェストエントリに含まれるハッシュ値の計算方法を示し、そのため署名の正しい検証には欠くことのできないものです。このキーワードは、動的または埋め込みコンテンツ、多国語ドキュメント用の複数ハッシュなどに使用します。

次に、マニフェストファイルでの Magic 属性の使用例を 2 つ示します。

        Name: http://www.example-scripts.com/index#script1
        SHA-256-Digest: (base64 representation of SHA-256 hash)
        Magic: JavaScript, Dynamic

        Name: http://www.example-tourist.com/guide.html
        SHA-256-Digest: (base64 representation of SHA-256 hash)
        SHA-256-Digest-French: (base64 representation of SHA-256 hash)
        SHA-256-Digest-German: (base64 representation of SHA-256 hash)
        Magic: Multilingual

最初の例では、これら Magic の値は http 問い合わせの結果がドキュメント自身ではなく、ドキュメントに埋め込まれたスクリプトであり、またそのスクリプトが動的に生成されるということを示します。この 2 つの情報は、マニフェストのダイジェスト値と比較し、有効な署名と比較するハッシュ値の計算方法を示します。

第 2 の例では、Magic 値は検索されたドキュメントの内容は特定の言語であるという合意を示し、検証のためのダイジェストの値は検索されたドキュメントを記述する言語に依存することを示します。

デジタル署名

デジタル署名とは、署名された .SF 署名ファイルです。これらはバイナリファイルであり、人間が解釈することは意図されていません。

デジタル署名ファイルは、.SF ファイルとファイル名は同じですが、拡張子が異なります。拡張子はデジタル署名のタイプによって変化します。

上に示されていない署名アルゴリズム用のデジタル署名ファイルは、META-INF ディレクトリに置き、「SIG-」という接頭辞を付ける必要があります。対応する署名ファイル (.SF ファイル) にも同じ接頭辞を付けなければなりません。

外部署名データをサポートしない形式については、ファイルは .SF ファイルの署名されたコピーで構成されることになります。したがって、一部のデータが重複する可能性があるため、ベリファイアは 2 つのファイルを比較する必要があります。

外部データをサポートする形式は、.SF ファイルを参照するか、暗黙的な参照によって計算を実行します。

各 .SF ファイルは複数のデジタル署名を持つ可能性がありますが、これらの署名は同じ正当なエンティティーによって生成される必要があります。

ファイル名の拡張子には、1 - 3 文字の英数字を使うことができます。認識されない拡張子は無視されます。

マニフェストおよび署名ファイルについて

ここでは、マニフェストおよび署名ファイルに適用されるその他の制約および規則について説明します。

JAR インデックス

概要

1.3 から、ネットワークアプリケーション、特にアプレットのクラスローダーによるクラス検索処理を最適化するために、JarIndex が導入されています。アプレットのクラスローダーの基本機能では、単純な線形検索アルゴリズムによって、内部検索パスの各要素が検索されます。内部検索パスは、「ARCHIVE」タグまたは「Class-Path」メイン属性から構築されます。クラスまたはリソースが検出されるまで、クラスローダーによって検索パスの各要素がダウンロードされて開かれます。クラスローダーによって、存在しないリソースの検索が行われた場合、アプリケーションまたはアプレットの jar ファイルがすべてダウンロードされることになります。この結果、大きなネットワークアプリケーションおよびアプレットの場合は、起動および応答が遅くなり、ネットワーク帯域幅が浪費される可能性があります。JarIndex メカニズムでは、アプレットに定義されている jar ファイルのコンテンツがすべて収集され、アプレットのクラスパスにある最初の jar ファイルのインデックスファイルにこの情報が格納されます。最初の jar ファイルがダウンロードされると、アプレットクラスローダーでは、収集されたコンテンツ情報を使って効率的に jar ファイルがダウンロードされます。

既存の jar ツールの機能も拡張されています。jar ファイルのリストが検査されてから、クラスおよびリソースが属している jar ファイルについてのディレクトリ情報が生成されます。このディレクトリ情報は、ルート jar ファイルの META-INF ディレクトリの INDEX.LIST という名前の、単純なテキストファイル内に格納されます。クラスローダーによって、ルート jar ファイルがロードされ、INDEX.LIST ファイルが読み込まれます。次に、そのファイルを使って、ファイル名とパッケージ名から jar ファイル名のリストへのマッピングを格納したハッシュテーブルが構築されます。クラスローダーによってクラスまたはリソースが検索される場合、ハッシュテーブルを問い合わせて、適切な jar ファイルが検出されてから、必要に応じてダウンロードされます。

クラスローダーによって、特定の jar ファイルで INDEX.LIST ファイルが検出されると、そのファイルにリストされた情報は常に信頼されます。クラスローダーによって特定のクラスのマッピングが検出されたあとで、リンクをたどってもそのクラスが検出されなかった場合は、InvalidJarIndexException がスローされます。この例外が発生した場合は、アプリケーション開発者は、拡張機能に対して jar ツールを実行し直し、インデックスファイルに正しい情報を取得する必要があります。

大量の領域オーバーヘッドの発生をアプリケーションで回避し、メモリー内のハッシュテーブルを高速で構築するために、INDEX.LIST ファイルの容量はできるかぎり小さくなるように管理されます。クラスのパッケージ名が null でない場合は、マッピングはパッケージレベルで記録されます。通常は、1 つのパッケージが 1 つの jar ファイルにマッピングされます。ある特定のパッケージが複数の jar ファイルにわたる場合、このパッケージは jar ファイルのリストにマッピングされます。リソースファイルにディレクトリの接頭辞がある場合は、マッピングはディレクトリレベルでも記録されます。パッケージ名が null のクラスの場合およびルートディレクトリにリソースファイルが格納されている場合にだけ、マッピングがファイルレベルで記録されます。

インデックスファイルの仕様

INDEX.LIST ファイルには、1 つ以上のセクションが含まれ、それぞれ 1 行の空白行で区切られています。セクションごとに 1 つの jar ファイルのコンテンツが定義されています。各セクションでは、jar ファイルのパス名を定義するヘッダーのあとに、パッケージ名またはファイル名のリストが 1 行ずつ続きます。すべての jar ファイルのパスは、ルート jar ファイルのコードベースを起点とする相対パスです。これらのパス名は、バンドル型拡張機能が現在の拡張機能メカニズムによって解釈される方法と同じ方法で解決されます。

インデックスファイルのファイル名またはパッケージ名に、ASCII 以外の文字が使われているときは、UTF-8 エンコーディングが使われます。
 

仕様

    index file :                   version-info blankline section*
    version-info :             JarIndex-Version: version-number
    version-number :       digit+{.digit+}*
    section :                     body blankline
    body :                        header name*
    header :                     char+.jar newline
    name :                       char+ newline
    char :                         any valid Unicode character except NULL, CR andLF
    blankline:                   newline newline
    newline :                     CR LF | LF | CR (not followed by LF)
    digit:                          {0-9}
 
INDEX.LIST ファイルは、jar -i を実行することによって生成されます。詳細は、jar のマニュアルページを参照してください。

下位互換性

新しいクラスのロード方式は、現在の拡張機能メカニズムを基にして開発されたアプリケーションと完全な下位互換性があります。クラスローダーによって最初の jar ファイルがロードされ、META-INF ディレクトリ内で INDEX.LIST ファイルが検出されたときは、インデックスハッシュテーブルが構築され、その拡張機能に対して新しいロード方式が使われます。それ以外の場合、クラスローダーでは元の線形検索アルゴリズムが使われます。

サービスプロバイダ

概要

META-INF/services ディレクトリ内のファイルは、サービスプロバイダの構成ファイルです。「サービス」とは、既知のインタフェースおよびクラス (通常は abstract クラス) のセットです。「サービスプロバイダ」とは、特定のサービスの実装です。通常、プロバイダのクラスによって、サービス自体に定義されているクラスのインタフェースとサブクラスが実装されます。サービスプロバイダを Java プラットフォームの実装にインストールするときは、拡張機能の形式、つまり、拡張機能の通常のディレクトリに配置される jar ファイルの形式で行われます。プロバイダを利用可能にするには、アプレットまたはアプリケーションのクラスパスに追加するか、プラットフォーム固有の方法を使います。

サービスは、abstract クラスによって表現されます。特定のサービスのプロバイダは、サービスのクラスを継承したいくつかの具象クラスで構成されています。サービスのクラスには、プロバイダ固有のデータおよびコードが含まれます。通常、プロバイダクラスには、プロバイダ自体がすべて含まれることはありません。要求時に実際のプロバイダを作成できるコードと、プロバイダが特定の要求を満たすことができるかどうかを識別するために必要な情報で構成されるプロキシになっています。プロバイダクラスの内容は、個別のサービスに大きく依存します。1 つのクラスまたはインタフェースでプロバイダクラスを統合することはできません。このため、このようなクラスは定義されていません。プロバイダクラスには、ルックアップ中にインスタンスを生成できるように、引数を取らないコンストラクタが必要です。

プロバイダ構成ファイル

サービスプロバイダは、リソースディレクトリ META-INF/services にプロバイダ構成ファイルを配置することによって識別されます。このファイルの名前は、完全指定された abstract サービスクラス名で構成する必要があります。このファイルには、改行文字で区切られた、一意の具象プロバイダクラス名のリストを含める必要があります。空白文字とタブ文字、および空白行は無視されます。コメント文字は「#」(0x23) で、行の最初のコメント文字に続く文字はすべて無視されます。ファイルは UTF-8 で符号化されている必要があります。

例

java.io.spi.CharCodec という名前のサービスクラスを想定します。このクラスには、次の 2 つの abstract メソッドがあります。

これらのメソッドは、渡されたエンコーディングを変換できない場合、適切なオブジェクトまたは null を返します。標準の CharCodec プロバイダでは、複数のエンコーディングがサポートされています。

sun.io.StandardCodec が CharCodec サービスのプロバイダの場合は、jar ファイルに META-INF/services/java.io.spi.CharCodec ファイルが含まれます。このファイルには、次の行が含まれます。

sun.io.StandardCodec    # Standard codecs for the platform

特定のエンコーディング名のエンコーダを検索するには、内部の I/O コードによって次のような処理が行われます。

   CharEncoder getEncoder(String encodingName) {
       Iterator ps = Service.providers(CharCodec.class);
       while (ps.hasNext()) {
           CharCodec cc = (CharCodec)ps.next();
           CharEncoder ce = cc.getEncoder(encodingName);
           if (ce != null)
               return ce;
       }
       return null;
   }

プロバイダのルックアップメカニズムは、常に呼び出し側のセキュリティーコンテキストで実行されます。信頼できるシステムコードでは、通常、このクラスのメソッドは特権付きのセキュリティーコンテキストから呼び出す必要があります。

API の詳細

パッケージ java.util.jar

関連項目

パッケージ java.security
パッケージ java.util.zip
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.